Miguel Ruiz / SDL_lib2

SDL Library

Dependents:   H261_decoder

SDL_thread.h@0:7fb6877b5d7c, 2016-09-22 (annotated)

Committer:
miruga27
Date:
Thu Sep 22 00:03:09 2016 +0000
Revision:
0:7fb6877b5d7c
SDL

Who changed what in which revision?

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