DRAFT |
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
fn |
the function to call in the new thread; see Remarks for details |
name |
the name of the thread; see Remarks for details |
data |
a pointer that is passed to fn |
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()
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.
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:
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
The following bugs were listed in the old wiki. Do any still apply in 1.3 or were they resolved by adding the instructions about _beginthread() and _endthread()?
(SDL 1.2.7) Even after the procedure started in the thread returns, there still exist some resources allocated to the thread. To free these resources use SDL_WaitThread() to wait for the thread to finish and obtain the status code of the thread. If not done so, SDL_CreateThread() will hang after about 1010 successfully created threads (tested on GNU/Linux). This is consistent with POSIX threads behavior where unless threads are explicitly detached using pthread_detach() or created using a pthread_attr initialized using pthread_attr_setdetachstate() passed at pthread_create(), they must be waited for using pthread_join() for their resources to be released. The SDL threads abstraction library does not provide the functions to detach a thread or to launch a thread in detached mode.
(SDL 1.2.9) On win32 (this wasn't observed on unix), the initial thread must be the one polling the SDL events. Otherwise, keyboard events are no longer caught. Moreover, it is recommended to use SDL_mixer and SDL blitting functions from within that initial thread as well, otherwise the system becomes unstable (also only under win32) despite the proper use of mutexes and conditional variables. This unfortunately limits a lot of the usefulness of threads when the software is also expected to run on win32.
*
Is there a way to kill/destroy/end/close a thread? Should it be listed here if there is?