Miguel Ruiz / SDL_lib

SDL standard library

Dependents:   H261_encoder

SDL_thread.h@0:dda4f4550403, 2016-09-07 (annotated)

Committer:
miruga27
Date:
Wed Sep 07 18:46:53 2016 +0000
Revision:
0:dda4f4550403
7/09/2016;

Who changed what in which revision?

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