DRAFT |
SDL_CreateThread
Use this function to create a new thread *with the same properties as the parent thread* -and/or- that does SDL_ThreadFunction() with the '''data'''.
Syntax
SDL_Thread* SDL_CreateThread(SDL_ThreadFunction fn,
void* data)
Function Parameters
fn |
the function to be run in the new thread; see Remarks for details |
data |
a void* user context parameter -and/or- passed directly to the thread function -or- a pointer to the data to be passed to the function in the new thread |
Return Value
Returns the new thread. Is this RV effectively the thread ID?
Should it be mentioned here that the function fn itself returns an int or is it sufficient to note that in the Remarks?
Code Examples
You can add your code example here
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.
*
fn is the function passed to SDL_CreateThread() and has the following syntax. It is passed a void* user context parameter and returns an int.
int (SDLCALL * SDL_ThreadFunction) (void *data)
Should this be in a gray box instead?
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 to 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?
*
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.8) On win32, keystrokes are caught in correctly in a thread, but SDL_EnableUNICODE (Does this function still exist in 1.3? It does not have a page currently.) does not work correctly. Specifically, .unicode contains the same value as .sym, not the modified version for SHFT, CTRL, etc.
(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?
Related Functions
SDL_GetThreadID ???
SDL_ThreadID ???
SDL_WaitThread ???