SDL_thread.h (13256B)
1/* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20*/ 21 22#ifndef SDL_thread_h_ 23#define SDL_thread_h_ 24 25/** 26 * \file SDL_thread.h 27 * 28 * Header for the SDL thread management routines. 29 */ 30 31#include "SDL_stdinc.h" 32#include "SDL_error.h" 33 34/* Thread synchronization primitives */ 35#include "SDL_atomic.h" 36#include "SDL_mutex.h" 37 38#include "begin_code.h" 39/* Set up for C function definitions, even when using C++ */ 40#ifdef __cplusplus 41extern "C" { 42#endif 43 44/* The SDL thread structure, defined in SDL_thread.c */ 45struct SDL_Thread; 46typedef struct SDL_Thread SDL_Thread; 47 48/* The SDL thread ID */ 49typedef unsigned long SDL_threadID; 50 51/* Thread local storage ID, 0 is the invalid ID */ 52typedef unsigned int SDL_TLSID; 53 54/** 55 * The SDL thread priority. 56 * 57 * \note On many systems you require special privileges to set high or time critical priority. 58 */ 59typedef enum { 60 SDL_THREAD_PRIORITY_LOW, 61 SDL_THREAD_PRIORITY_NORMAL, 62 SDL_THREAD_PRIORITY_HIGH, 63 SDL_THREAD_PRIORITY_TIME_CRITICAL 64} SDL_ThreadPriority; 65 66/** 67 * The function passed to SDL_CreateThread(). 68 * It is passed a void* user context parameter and returns an int. 69 */ 70typedef int (SDLCALL * SDL_ThreadFunction) (void *data); 71 72#if defined(__WIN32__) 73/** 74 * \file SDL_thread.h 75 * 76 * We compile SDL into a DLL. This means, that it's the DLL which 77 * creates a new thread for the calling process with the SDL_CreateThread() 78 * API. There is a problem with this, that only the RTL of the SDL2.DLL will 79 * be initialized for those threads, and not the RTL of the calling 80 * application! 81 * 82 * To solve this, we make a little hack here. 83 * 84 * We'll always use the caller's _beginthread() and _endthread() APIs to 85 * start a new thread. This way, if it's the SDL2.DLL which uses this API, 86 * then the RTL of SDL2.DLL will be used to create the new thread, and if it's 87 * the application, then the RTL of the application will be used. 88 * 89 * So, in short: 90 * Always use the _beginthread() and _endthread() of the calling runtime 91 * library! 92 */ 93#define SDL_PASSED_BEGINTHREAD_ENDTHREAD 94#include <process.h> /* _beginthreadex() and _endthreadex() */ 95 96typedef uintptr_t (__cdecl * pfnSDL_CurrentBeginThread) 97 (void *, unsigned, unsigned (__stdcall *func)(void *), 98 void * /*arg*/, unsigned, unsigned * /* threadID */); 99typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code); 100 101#ifndef SDL_beginthread 102#define SDL_beginthread _beginthreadex 103#endif 104#ifndef SDL_endthread 105#define SDL_endthread _endthreadex 106#endif 107 108/** 109 * Create a thread. 110 */ 111extern DECLSPEC SDL_Thread *SDLCALL 112SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, 113 pfnSDL_CurrentBeginThread pfnBeginThread, 114 pfnSDL_CurrentEndThread pfnEndThread); 115 116extern DECLSPEC SDL_Thread *SDLCALL 117SDL_CreateThreadWithStackSize(int (SDLCALL * fn) (void *), 118 const char *name, const size_t stacksize, void *data, 119 pfnSDL_CurrentBeginThread pfnBeginThread, 120 pfnSDL_CurrentEndThread pfnEndThread); 121 122 123/** 124 * Create a thread. 125 */ 126#if defined(SDL_CreateThread) && SDL_DYNAMIC_API 127#undef SDL_CreateThread 128#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) 129#undef SDL_CreateThreadWithStackSize 130#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) 131#else 132#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) 133#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, data, (pfnSDL_CurrentBeginThread)_beginthreadex, (pfnSDL_CurrentEndThread)SDL_endthread) 134#endif 135 136#elif defined(__OS2__) 137/* 138 * just like the windows case above: We compile SDL2 139 * into a dll with Watcom's runtime statically linked. 140 */ 141#define SDL_PASSED_BEGINTHREAD_ENDTHREAD 142 143#ifndef __EMX__ 144#include <process.h> 145#else 146#include <stdlib.h> 147#endif 148 149typedef int (*pfnSDL_CurrentBeginThread)(void (*func)(void *), void *, unsigned, void * /*arg*/); 150typedef void (*pfnSDL_CurrentEndThread)(void); 151 152#ifndef SDL_beginthread 153#define SDL_beginthread _beginthread 154#endif 155#ifndef SDL_endthread 156#define SDL_endthread _endthread 157#endif 158 159extern DECLSPEC SDL_Thread *SDLCALL 160SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, 161 pfnSDL_CurrentBeginThread pfnBeginThread, 162 pfnSDL_CurrentEndThread pfnEndThread); 163extern DECLSPEC SDL_Thread *SDLCALL 164SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data, 165 pfnSDL_CurrentBeginThread pfnBeginThread, 166 pfnSDL_CurrentEndThread pfnEndThread); 167 168#if defined(SDL_CreateThread) && SDL_DYNAMIC_API 169#undef SDL_CreateThread 170#define SDL_CreateThread(fn, name, data) SDL_CreateThread_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) 171#undef SDL_CreateThreadWithStackSize 172#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize_REAL(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) 173#else 174#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) 175#define SDL_CreateThreadWithStackSize(fn, name, stacksize, data) SDL_CreateThreadWithStackSize(fn, name, stacksize, data, (pfnSDL_CurrentBeginThread)SDL_beginthread, (pfnSDL_CurrentEndThread)SDL_endthread) 176#endif 177 178#else 179 180/** 181 * Create a thread with a default stack size. 182 * 183 * This is equivalent to calling: 184 * SDL_CreateThreadWithStackSize(fn, name, 0, data); 185 */ 186extern DECLSPEC SDL_Thread *SDLCALL 187SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); 188 189/** 190 * Create a thread. 191 * 192 * Thread naming is a little complicated: Most systems have very small 193 * limits for the string length (Haiku has 32 bytes, Linux currently has 16, 194 * Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll 195 * have to see what happens with your system's debugger. The name should be 196 * UTF-8 (but using the naming limits of C identifiers is a better bet). 197 * There are no requirements for thread naming conventions, so long as the 198 * string is null-terminated UTF-8, but these guidelines are helpful in 199 * choosing a name: 200 * 201 * http://stackoverflow.com/questions/149932/naming-conventions-for-threads 202 * 203 * If a system imposes requirements, SDL will try to munge the string for 204 * it (truncate, etc), but the original string contents will be available 205 * from SDL_GetThreadName(). 206 * 207 * The size (in bytes) of the new stack can be specified. Zero means "use 208 * the system default" which might be wildly different between platforms 209 * (x86 Linux generally defaults to eight megabytes, an embedded device 210 * might be a few kilobytes instead). 211 * 212 * In SDL 2.1, stacksize will be folded into the original SDL_CreateThread 213 * function. 214 */ 215extern DECLSPEC SDL_Thread *SDLCALL 216SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const size_t stacksize, void *data); 217 218#endif 219 220/** 221 * Get the thread name, as it was specified in SDL_CreateThread(). 222 * This function returns a pointer to a UTF-8 string that names the 223 * specified thread, or NULL if it doesn't have a name. This is internal 224 * memory, not to be free()'d by the caller, and remains valid until the 225 * specified thread is cleaned up by SDL_WaitThread(). 226 */ 227extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread); 228 229/** 230 * Get the thread identifier for the current thread. 231 */ 232extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void); 233 234/** 235 * Get the thread identifier for the specified thread. 236 * 237 * Equivalent to SDL_ThreadID() if the specified thread is NULL. 238 */ 239extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread); 240 241/** 242 * Set the priority for the current thread 243 */ 244extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); 245 246/** 247 * Wait for a thread to finish. Threads that haven't been detached will 248 * remain (as a "zombie") until this function cleans them up. Not doing so 249 * is a resource leak. 250 * 251 * Once a thread has been cleaned up through this function, the SDL_Thread 252 * that references it becomes invalid and should not be referenced again. 253 * As such, only one thread may call SDL_WaitThread() on another. 254 * 255 * The return code for the thread function is placed in the area 256 * pointed to by \c status, if \c status is not NULL. 257 * 258 * You may not wait on a thread that has been used in a call to 259 * SDL_DetachThread(). Use either that function or this one, but not 260 * both, or behavior is undefined. 261 * 262 * It is safe to pass NULL to this function; it is a no-op. 263 */ 264extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status); 265 266/** 267 * A thread may be "detached" to signify that it should not remain until 268 * another thread has called SDL_WaitThread() on it. Detaching a thread 269 * is useful for long-running threads that nothing needs to synchronize 270 * with or further manage. When a detached thread is done, it simply 271 * goes away. 272 * 273 * There is no way to recover the return code of a detached thread. If you 274 * need this, don't detach the thread and instead use SDL_WaitThread(). 275 * 276 * Once a thread is detached, you should usually assume the SDL_Thread isn't 277 * safe to reference again, as it will become invalid immediately upon 278 * the detached thread's exit, instead of remaining until someone has called 279 * SDL_WaitThread() to finally clean it up. As such, don't detach the same 280 * thread more than once. 281 * 282 * If a thread has already exited when passed to SDL_DetachThread(), it will 283 * stop waiting for a call to SDL_WaitThread() and clean up immediately. 284 * It is not safe to detach a thread that might be used with SDL_WaitThread(). 285 * 286 * You may not call SDL_WaitThread() on a thread that has been detached. 287 * Use either that function or this one, but not both, or behavior is 288 * undefined. 289 * 290 * It is safe to pass NULL to this function; it is a no-op. 291 */ 292extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread); 293 294/** 295 * \brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific. 296 * 297 * \return The newly created thread local storage identifier, or 0 on error 298 * 299 * \code 300 * static SDL_SpinLock tls_lock; 301 * static SDL_TLSID thread_local_storage; 302 * 303 * void SetMyThreadData(void *value) 304 * { 305 * if (!thread_local_storage) { 306 * SDL_AtomicLock(&tls_lock); 307 * if (!thread_local_storage) { 308 * thread_local_storage = SDL_TLSCreate(); 309 * } 310 * SDL_AtomicUnlock(&tls_lock); 311 * } 312 * SDL_TLSSet(thread_local_storage, value, 0); 313 * } 314 * 315 * void *GetMyThreadData(void) 316 * { 317 * return SDL_TLSGet(thread_local_storage); 318 * } 319 * \endcode 320 * 321 * \sa SDL_TLSGet() 322 * \sa SDL_TLSSet() 323 */ 324extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); 325 326/** 327 * \brief Get the value associated with a thread local storage ID for the current thread. 328 * 329 * \param id The thread local storage ID 330 * 331 * \return The value associated with the ID for the current thread, or NULL if no value has been set. 332 * 333 * \sa SDL_TLSCreate() 334 * \sa SDL_TLSSet() 335 */ 336extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); 337 338/** 339 * \brief Set the value associated with a thread local storage ID for the current thread. 340 * 341 * \param id The thread local storage ID 342 * \param value The value to associate with the ID for the current thread 343 * \param destructor A function called when the thread exits, to free the value. 344 * 345 * \return 0 on success, -1 on error 346 * 347 * \sa SDL_TLSCreate() 348 * \sa SDL_TLSGet() 349 */ 350extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (SDLCALL *destructor)(void*)); 351 352 353/* Ends C function definitions when using C++ */ 354#ifdef __cplusplus 355} 356#endif 357#include "close_code.h" 358 359#endif /* SDL_thread_h_ */ 360 361/* vi: set ts=4 sw=4 expandtab: */