My Project
|
#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "SDL_atomic.h"
#include "SDL_mutex.h"
#include "begin_code.h"
#include "close_code.h"
Go to the source code of this file.
Typedefs | |
typedef struct SDL_Thread | SDL_Thread |
typedef unsigned long | SDL_threadID |
typedef unsigned int | SDL_TLSID |
typedef int(SDLCALL * | SDL_ThreadFunction) (void *data) |
Enumerations | |
enum | SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, SDL_THREAD_PRIORITY_NORMAL, SDL_THREAD_PRIORITY_HIGH } |
Functions | |
DECLSPEC SDL_Thread *SDLCALL | SDL_CreateThread (SDL_ThreadFunction fn, const char *name, void *data) |
DECLSPEC const char *SDLCALL | SDL_GetThreadName (SDL_Thread *thread) |
DECLSPEC SDL_threadID SDLCALL | SDL_ThreadID (void) |
DECLSPEC SDL_threadID SDLCALL | SDL_GetThreadID (SDL_Thread *thread) |
DECLSPEC int SDLCALL | SDL_SetThreadPriority (SDL_ThreadPriority priority) |
DECLSPEC void SDLCALL | SDL_WaitThread (SDL_Thread *thread, int *status) |
DECLSPEC void SDLCALL | SDL_DetachThread (SDL_Thread *thread) |
DECLSPEC SDL_TLSID SDLCALL | SDL_TLSCreate (void) |
Create an identifier that is globally visible to all threads but refers to data that is thread-specific. More... | |
DECLSPEC void *SDLCALL | SDL_TLSGet (SDL_TLSID id) |
Get the value associated with a thread local storage ID for the current thread. More... | |
DECLSPEC int SDLCALL | SDL_TLSSet (SDL_TLSID id, const void *value, void(*destructor)(void *)) |
Set the value associated with a thread local storage ID for the current thread. More... | |
Header for the SDL thread management routines.
typedef int(SDLCALL * SDL_ThreadFunction) (void *data) |
The function passed to SDL_CreateThread(). It is passed a void* user context parameter and returns an int.
enum SDL_ThreadPriority |
The SDL thread priority.
DECLSPEC SDL_Thread* SDLCALL 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 (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().
DECLSPEC void SDLCALL SDL_DetachThread | ( | SDL_Thread * | thread | ) |
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.
DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID | ( | SDL_Thread * | thread | ) |
Get the thread identifier for the specified thread.
Equivalent to SDL_ThreadID() if the specified thread is NULL.
DECLSPEC const char* SDLCALL SDL_GetThreadName | ( | SDL_Thread * | thread | ) |
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().
DECLSPEC int SDLCALL SDL_SetThreadPriority | ( | SDL_ThreadPriority | priority | ) |
Set the priority for the current thread
DECLSPEC SDL_threadID SDLCALL SDL_ThreadID | ( | void | ) |
Get the thread identifier for the current thread.
DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate | ( | void | ) |
Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
DECLSPEC void* SDLCALL SDL_TLSGet | ( | SDL_TLSID | id | ) |
Get the value associated with a thread local storage ID for the current thread.
id | The thread local storage ID |
DECLSPEC int SDLCALL SDL_TLSSet | ( | SDL_TLSID | id, |
const void * | value, | ||
void(*)(void *) | destructor | ||
) |
Set the value associated with a thread local storage ID for the current thread.
id | The thread local storage ID |
value | The value to associate with the ID for the current thread |
destructor | A function called when the thread exits, to free the value. |
DECLSPEC void SDLCALL SDL_WaitThread | ( | SDL_Thread * | thread, |
int * | status | ||
) |
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 status
, if 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.