SDL_CreateThread

Use this function to create a new thread with the same properties as the parent thread.

Syntax

SDL_Thread* SDL_CreateThread(SDL_ThreadFunction fn,
                             const char*        name,
                             void*              data)

Function Parameters

Return Value

Returns the new thread pointer on success, NULL if the new thread could not be created. This is a pointer to an SDL defined device independent thread information structure. The returned thread pointer will be used for any subsequent calls to manage this thread.

Code Examples

#include <stdio.h>
#include <SDL_thread.h>
#include <SDL_timer.h>

int TestThread( void *ptr );

int main(int argc, char *argv[])
{
        SDL_Thread *thread;
        int         threadReturnValue;

        printf("\nSimple SDL_CreateThread test:");

        // Simply create a thread
        thread = SDL_CreateThread( TestThread, "TestThread", (void *)NULL);

        if( NULL == thread )
           printf("\nSDL_CreateThread failed: %s\n", SDL_GetError());
        else
        {
           SDL_WaitThread( thread, &threadReturnValue);
           printf("\nThread returned value:%d", threadReturnValue);
        }

        return 1;
}

// Very simple thread - counts 0 to 9 delaying 50ms between increments
int TestThread( void *ptr )
{
        int        cnt;

        for(cnt=0;cnt<10;cnt++)
        {
                printf( "\nThread counter: %d", cnt);
                SDL_Delay(50);
        }

        return cnt;
}

Output:

Simple SDL_CreateThread test:
Thread counter: 0
Thread counter: 1
Thread counter: 2
Thread counter: 3
Thread counter: 4
Thread counter: 5
Thread counter: 6
Thread counter: 7
Thread counter: 8
Thread counter: 9
Thread returned value:10

Remarks

SDL_CreateThread() creates a new thread of execution that shares all of its parent's global memory, signal handlers, file descriptors, etc, and runs the function fn, passing it the void pointer data. The thread quits when fn returns.

The function prototype for fn is:

• int SDL_ThreadFunction(void* data)

  • where its parameter is:

  data	what was passed as data to SDL_CreateThread()

Implementation Notes

Always use the caller's _beginthread() and _endthread() APIs to start a new thread. This way, if it's the SDL.DLL which uses this API, then the RTL of SDL.DLL will be used to create the new thread, and if it's the application, then the RTL of the application will be used. This information is also listed on the main Category page in more detail but it seems relevant to list at least some of it here as well. Should the header be referenced as a link for more information?

Is the int that is returned equivalent to the thread ID or is it just an integer to indicate success or failure? Should it be further defined here?

Thread naming is a little complicated: Most systems have very small limits for the string length (BeOS has 32 bytes, Linux currently has 16, Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll have to see what happens with your system's debugger. The name should be UTF-8 (but using the naming limits of C identifiers is a better bet).

There are no requirements for thread naming conventions, so long as the string is null-terminated UTF-8, but these guidelines are helpful in choosing a name:

• http://stackoverflow.com/questions/149932/naming-conventions-for-threads

If a system imposes requirements, SDL will try to munge the string for it (truncate, etc), but the original string contents will be available from SDL_GetThreadName().

Related Functions

• SDL_GetThreadID ???

• SDL_GetThreadName

• SDL_ThreadID ???

. SDL_WaitThread ???

CategoryAPI, CategoryThread