diff options
Diffstat (limited to 'src/SDL2/include/SDL_thread.h')
| -rw-r--r-- | src/SDL2/include/SDL_thread.h | 61 |
1 files changed, 54 insertions, 7 deletions
diff --git a/src/SDL2/include/SDL_thread.h b/src/SDL2/include/SDL_thread.h index c878c3ab..4e48cc34 100644 --- a/src/SDL2/include/SDL_thread.h +++ b/src/SDL2/include/SDL_thread.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2013 Sam Lantinga <slouken@libsdl.org> + Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org> This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,9 +51,10 @@ typedef unsigned long SDL_threadID; /* Thread local storage ID, 0 is the invalid ID */ typedef unsigned int SDL_TLSID; -/* The SDL thread priority +/** + * The SDL thread priority. * - * Note: On many systems you require special privileges to set high priority. + * \note On many systems you require special privileges to set high priority. */ typedef enum { SDL_THREAD_PRIORITY_LOW, @@ -61,8 +62,9 @@ typedef enum { SDL_THREAD_PRIORITY_HIGH } SDL_ThreadPriority; -/* The function passed to SDL_CreateThread() - It is passed a void* user context parameter and returns an int. +/** + * The function passed to SDL_CreateThread(). + * It is passed a void* user context parameter and returns an int. */ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); @@ -109,7 +111,12 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, /** * Create a thread. */ +#if defined(SDL_CreateThread) && SDL_DYNAMIC_API +#undef SDL_CreateThread +#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)_endthreadex) +#else #define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)_endthreadex) +#endif #else @@ -117,7 +124,7 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, * Create a thread. * * Thread naming is a little complicated: Most systems have very small - * limits for the string length (BeOS has 32 bytes, Linux currently has 16, + * limits for the string length (Haiku 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). @@ -163,14 +170,54 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread); extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); /** - * Wait for a thread to finish. + * Wait for a thread to finish. Threads that haven't been detached will + * remain (as a "zombie") until this function cleans them up. Not doing so + * is a resource leak. + * + * Once a thread has been cleaned up through this function, the SDL_Thread + * that references it becomes invalid and should not be referenced again. + * As such, only one thread may call SDL_WaitThread() on another. * * The return code for the thread function is placed in the area * pointed to by \c status, if \c status is not NULL. + * + * You may not wait on a thread that has been used in a call to + * SDL_DetachThread(). Use either that function or this one, but not + * both, or behavior is undefined. + * + * It is safe to pass NULL to this function; it is a no-op. */ extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status); /** + * A thread may be "detached" to signify that it should not remain until + * another thread has called SDL_WaitThread() on it. Detaching a thread + * is useful for long-running threads that nothing needs to synchronize + * with or further manage. When a detached thread is done, it simply + * goes away. + * + * There is no way to recover the return code of a detached thread. If you + * need this, don't detach the thread and instead use SDL_WaitThread(). + * + * Once a thread is detached, you should usually assume the SDL_Thread isn't + * safe to reference again, as it will become invalid immediately upon + * the detached thread's exit, instead of remaining until someone has called + * SDL_WaitThread() to finally clean it up. As such, don't detach the same + * thread more than once. + * + * If a thread has already exited when passed to SDL_DetachThread(), it will + * stop waiting for a call to SDL_WaitThread() and clean up immediately. + * It is not safe to detach a thread that might be used with SDL_WaitThread(). + * + * You may not call SDL_WaitThread() on a thread that has been detached. + * Use either that function or this one, but not both, or behavior is + * undefined. + * + * It is safe to pass NULL to this function; it is a no-op. + */ +extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread); + +/** * \brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific. * * \return The newly created thread local storage identifier, or 0 on error |