|
Size: 4483
Comment: add content
|
Size: 4550
Comment: Updated information on what exactly is returned by this function
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| ||<tablewidth="100%" style="color: #FF0000;" :> DRAFT|| | ||<tablewidth="100%"style="color: rgb(255, 0, 0); text-align: center;">DRAFT || |
| Line 6: | Line 7: |
| 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'''`. | Use this function to create a new hread with the same properties as the parent thread. |
| Line 15: | Line 16: |
| == Function Parameters == ||'''fn''' ||^The function to be run in the new thread, see [[#Remarks|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^ || |
|
| Line 16: | Line 20: |
| == Function Parameters == ||'''fn'''||^the function to be run in the new thread^; see [[#Remarks|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^|| |
|
| Line 21: | Line 22: |
| ^Returns a pointer to the new thread.^ <<Color2(green,Is this RV effectively the thread ID?)>> | Returns the new thread pointer. This is a pointer to an SDL defined device independent thread information structure. The returned thread pointer will be used for any subsuequent calls to manage this thread. |
| Line 29: | Line 30: |
| Line 33: | Line 33: |
| '''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)}}}<<BR>> <<Color2(green,Should this be in a gray box instead?)>> |
'''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)}}}<<BR>> <<Color2(green,Should this be in a gray box instead?)>> |
| Line 45: | Line 45: |
| (SDL 1.2.8) On win32, keystrokes are caught in correctly in a thread, but SDL_EnableUNICODE <<Color2(green,(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.8) On win32, keystrokes are caught in correctly in a thread, but SDL_EnableUNICODE <<Color2(green,(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. |
| Line 52: | Line 52: |
| .[[SDL_GetThreadID]] ??? .[[SDL_ThreadID]] ??? .[[SDL_WaitThread]] ??? |
. [[SDL_GetThreadID]] ??? . [[SDL_ThreadID]] ??? . [[SDL_WaitThread]] ??? |
| Line 57: | Line 57: |
| [[CategoryAPI]], [[CategoryThread]] | [[CategoryAPI]], CategoryThread |
DRAFT |
SDL_CreateThread
Use this function to create a new hread with the same properties as the parent thread.
Contents
Syntax
SDL_Thread* SDL_CreateThread(SDL_ThreadFunction fn,
void* data)
Function Parameters
fn |
The function to be run in the new thread, see [[#Remarks|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 pointer. This is a pointer to an SDL defined device independent thread information structure. The returned thread pointer will be used for any subsuequent calls to manage this thread.
green
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)
green
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. green
green
*
green
(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 green
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.
*
green
Related Functions
SDL_GetThreadID ???
SDL_ThreadID ???
SDL_WaitThread ???
