X-Git-Url: https://git.ucc.asn.au/?p=ipdf%2Fcode.git;a=blobdiff_plain;f=contrib%2Finclude%2FSDL2%2FSDL_thread.h;fp=contrib%2Finclude%2FSDL2%2FSDL_thread.h;h=4e48cc34c1796c3294dcee8b5ab4d6f0cd84caca;hp=0000000000000000000000000000000000000000;hb=26524b787a61cb6d8bb5f2f6925855768ac9471f;hpb=fdc6f69d40cf7e872218ec48493534cc3b85c852 diff --git a/contrib/include/SDL2/SDL_thread.h b/contrib/include/SDL2/SDL_thread.h new file mode 100644 index 0000000..4e48cc3 --- /dev/null +++ b/contrib/include/SDL2/SDL_thread.h @@ -0,0 +1,287 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2014 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#ifndef _SDL_thread_h +#define _SDL_thread_h + +/** + * \file SDL_thread.h + * + * Header for the SDL thread management routines. + */ + +#include "SDL_stdinc.h" +#include "SDL_error.h" + +/* Thread synchronization primitives */ +#include "SDL_atomic.h" +#include "SDL_mutex.h" + +#include "begin_code.h" +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/* The SDL thread structure, defined in SDL_thread.c */ +struct SDL_Thread; +typedef struct SDL_Thread SDL_Thread; + +/* The SDL thread ID */ +typedef unsigned long SDL_threadID; + +/* Thread local storage ID, 0 is the invalid ID */ +typedef unsigned int SDL_TLSID; + +/** + * The SDL thread priority. + * + * \note On many systems you require special privileges to set high priority. + */ +typedef enum { + SDL_THREAD_PRIORITY_LOW, + SDL_THREAD_PRIORITY_NORMAL, + SDL_THREAD_PRIORITY_HIGH +} SDL_ThreadPriority; + +/** + * 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); + +#if defined(__WIN32__) && !defined(HAVE_LIBC) +/** + * \file SDL_thread.h + * + * We compile SDL into a DLL. This means, that it's the DLL which + * creates a new thread for the calling process with the SDL_CreateThread() + * API. There is a problem with this, that only the RTL of the SDL.DLL will + * be initialized for those threads, and not the RTL of the calling + * application! + * + * To solve this, we make a little hack here. + * + * We'll 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. + * + * So, in short: + * Always use the _beginthread() and _endthread() of the calling runtime + * library! + */ +#define SDL_PASSED_BEGINTHREAD_ENDTHREAD +#include /* This has _beginthread() and _endthread() defined! */ + +typedef uintptr_t(__cdecl * pfnSDL_CurrentBeginThread) (void *, unsigned, + unsigned (__stdcall * + func) (void + *), + void *arg, unsigned, + unsigned *threadID); +typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code); + +/** + * Create a thread. + */ +extern DECLSPEC SDL_Thread *SDLCALL +SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data, + pfnSDL_CurrentBeginThread pfnBeginThread, + pfnSDL_CurrentEndThread pfnEndThread); + +/** + * 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 + +/** + * Create a thread. + * + * Thread naming is a little complicated: Most systems have very small + * 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). + * There are no requirements for thread naming conventions, so long as the + * string is null-terminated UTF-8, but these guidelines are helpful in + * choosing a name: + * + * http://stackoverflow.com/questions/149932/naming-conventions-for-threads + * + * If a system imposes requirements, SDL will try to munge the string for + * it (truncate, etc), but the original string contents will be available + * from SDL_GetThreadName(). + */ +extern DECLSPEC SDL_Thread *SDLCALL +SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); + +#endif + +/** + * Get the thread name, as it was specified in SDL_CreateThread(). + * This function returns a pointer to a UTF-8 string that names the + * specified thread, or NULL if it doesn't have a name. This is internal + * memory, not to be free()'d by the caller, and remains valid until the + * specified thread is cleaned up by SDL_WaitThread(). + */ +extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread); + +/** + * Get the thread identifier for the current thread. + */ +extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void); + +/** + * Get the thread identifier for the specified thread. + * + * Equivalent to SDL_ThreadID() if the specified thread is NULL. + */ +extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread); + +/** + * Set the priority for the current thread + */ +extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); + +/** + * 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 + * + * \code + * static SDL_SpinLock tls_lock; + * static SDL_TLSID thread_local_storage; + * + * void SetMyThreadData(void *value) + * { + * if (!thread_local_storage) { + * SDL_AtomicLock(&tls_lock); + * if (!thread_local_storage) { + * thread_local_storage = SDL_TLSCreate(); + * } + * SDL_AtomicUnLock(&tls_lock); + * } + * SDL_TLSSet(thread_local_storage, value); + * } + * + * void *GetMyThreadData(void) + * { + * return SDL_TLSGet(thread_local_storage); + * } + * \endcode + * + * \sa SDL_TLSGet() + * \sa SDL_TLSSet() + */ +extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(void); + +/** + * \brief Get the value associated with a thread local storage ID for the current thread. + * + * \param id The thread local storage ID + * + * \return The value associated with the ID for the current thread, or NULL if no value has been set. + * + * \sa SDL_TLSCreate() + * \sa SDL_TLSSet() + */ +extern DECLSPEC void * SDLCALL SDL_TLSGet(SDL_TLSID id); + +/** + * \brief Set the value associated with a thread local storage ID for the current thread. + * + * \param id The thread local storage ID + * \param value The value to associate with the ID for the current thread + * \param destructor A function called when the thread exits, to free the value. + * + * \return 0 on success, -1 on error + * + * \sa SDL_TLSCreate() + * \sa SDL_TLSGet() + */ +extern DECLSPEC int SDLCALL SDL_TLSSet(SDL_TLSID id, const void *value, void (*destructor)(void*)); + + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include "close_code.h" + +#endif /* _SDL_thread_h */ + +/* vi: set ts=4 sw=4 expandtab: */