Thread Management

Thread Management. More...

Classes
struct	SDL::ThreadBase
	The SDL thread object. More...
struct	SDL::ThreadRef
	Handle to a non owned thread. More...
struct	SDL::Thread
	Handle to an owned thread. More...

Typedefs
using	SDL::ThreadID = SDL_ThreadID
	A unique numeric ID that identifies a thread.
using	SDL::TLSID = AtomicInt
	Thread local storage ID.
using	SDL::ThreadFunction = SDL_ThreadFunction
	The function passed to ThreadBase.ThreadBase() as the new thread's entry point.
using	SDL::ThreadCB = std::function< int()>
	The function passed to ThreadBase.ThreadBase() as the new thread's entry point.
using	SDL::TLSDestructorCallback = SDL_TLSDestructorCallback
	The callback used to cleanup data passed to SetTLS.
using	SDL::ThreadPriority = SDL_ThreadPriority
	The SDL thread priority.
using	SDL::ThreadState = SDL_ThreadState
	The SDL thread state.

Functions
ThreadID	SDL::GetCurrentThreadID ()
	Get the thread identifier for the current thread.
void *	SDL::GetTLS (TLSID *id)
	Get the current thread's value associated with a thread local storage ID.
void	SDL::SetTLS (TLSID *id, const void *value, TLSDestructorCallback destructor)
	Set the current thread's value associated with a thread local storage ID.
void	SDL::CleanupTLS ()
	Cleanup all TLS data for this thread.

Variables
constexpr ThreadPriority	SDL::THREAD_PRIORITY_LOW = SDL_THREAD_PRIORITY_LOW
	LOW.
constexpr ThreadPriority	SDL::THREAD_PRIORITY_NORMAL
	NORMAL.
constexpr ThreadPriority	SDL::THREAD_PRIORITY_HIGH
	HIGH.
constexpr ThreadPriority	SDL::THREAD_PRIORITY_TIME_CRITICAL
	TIME_CRITICAL.
constexpr ThreadState	SDL::THREAD_UNKNOWN
	The thread is not valid.
constexpr ThreadState	SDL::THREAD_ALIVE
	The thread is currently running.
constexpr ThreadState	SDL::THREAD_DETACHED
	The thread is detached and can't be waited on.
constexpr ThreadState	SDL::THREAD_COMPLETE = SDL_THREAD_COMPLETE
	The thread has finished and should be cleaned up with ThreadBase.Wait()

Detailed Description

This is provided for compatibility and completeness, we advise you to use std's thread facilities.

SDL offers cross-platform thread management functions. These are mostly concerned with starting threads, setting their priority, and dealing with their termination.

In addition, there is support for Thread Local Storage (data that is unique to each thread, but accessed from a single key).

On platforms without thread support (such as Emscripten when built without pthreads), these functions still exist, but things like ThreadBase.ThreadBase() will report failure without doing anything.

If you're going to work with threads, you almost certainly need to have a good understanding of [CategoryMutex](CategoryMutex) as well.

Typedef Documentation

ThreadCB

using SDL::ThreadCB = typedef std::function<int()>

Returns

a value that can be reported through ThreadBase.Wait().

Since

This datatype is available since SDL 3.2.0.

ThreadFunction

using SDL::ThreadFunction = typedef SDL_ThreadFunction

Parameters

data	what was passed as data to ThreadBase.ThreadBase().

Returns

a value that can be reported through ThreadBase.Wait().

Since

This datatype is available since SDL 3.2.0.

ThreadID

using SDL::ThreadID = typedef SDL_ThreadID

These are different from ThreadBase objects, which are generally what an application will operate on, but having a way to uniquely identify a thread can be useful at times.

Since

This datatype is available since SDL 3.2.0.

See also

ThreadBase.GetID

GetCurrentThreadID

ThreadPriority

using SDL::ThreadPriority = typedef SDL_ThreadPriority

SDL will make system changes as necessary in order to apply the thread priority. Code which attempts to control thread state related to priority should be aware that calling ThreadBase.SetCurrentPriority may alter such state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior.

Since

This enum is available since SDL 3.2.0.

ThreadState

using SDL::ThreadState = typedef SDL_ThreadState

The current state of a thread can be checked by calling ThreadBase.GetState.

Since

This enum is available since SDL 3.2.0.

See also

ThreadBase.GetState

TLSDestructorCallback

using SDL::TLSDestructorCallback = typedef SDL_TLSDestructorCallback

This is called when a thread exits, to allow an app to free any resources.

Parameters

value

a pointer previously handed to SetTLS.

Since

This datatype is available since SDL 3.2.0.

See also

SetTLS

TLSID

using SDL::TLSID = typedef AtomicInt

0 is the invalid ID. An app can create these and then set data for these IDs that is unique to each thread.

Since

This datatype is available since SDL 3.2.0.

See also

GetTLS

SetTLS

Function Documentation

CleanupTLS()

void SDL::CleanupTLS ( )

inline

If you are creating your threads outside of SDL and then calling SDL functions, you should call this function before your thread exits, to properly clean up SDL memory.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

GetCurrentThreadID()

ThreadID SDL::GetCurrentThreadID ( )

inline

This thread identifier is as reported by the underlying operating system. If SDL is running on a platform that does not support threads the return value will always be zero.

This function also returns a valid thread ID when called from the main thread.

Returns

the ID of the current thread.

Since

This function is available since SDL 3.2.0.

See also

ThreadBase.GetID

GetTLS()

void * SDL::GetTLS ( TLSID *  id )

inline

Parameters

id	a pointer to the thread local storage ID, may not be nullptr.

Returns

the value associated with the ID for the current thread or nullptr if no value has been set; call GetError() for more information.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

SetTLS

SetTLS()

void SDL::SetTLS ( TLSID *  id, const void *  value, TLSDestructorCallback  destructor  )

inline

If the thread local storage ID is not initialized (the value is 0), a new ID will be created in a thread-safe way, so all calls using a pointer to the same ID will refer to the same local storage.

Note that replacing a value from a previous call to this function on the same thread does not call the previous value's destructor!

destructor can be nullptr; it is assumed that value does not need to be cleaned up if so.

Parameters

id	a pointer to the thread local storage ID, may not be nullptr.
value	the value to associate with the ID for the current thread.
destructor	a function called when the thread exits, to free the value, may be nullptr.

Exceptions

Error

on failure.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

GetTLS

Variable Documentation

THREAD_ALIVE

constexpr ThreadState SDL::THREAD_ALIVE

constexpr

Initial value:

=
  SDL_THREAD_ALIVE

THREAD_DETACHED

constexpr ThreadState SDL::THREAD_DETACHED

constexpr

Initial value:

=
  SDL_THREAD_DETACHED

THREAD_PRIORITY_HIGH

constexpr ThreadPriority SDL::THREAD_PRIORITY_HIGH

constexpr

Initial value:

=
  SDL_THREAD_PRIORITY_HIGH

THREAD_PRIORITY_NORMAL

constexpr ThreadPriority SDL::THREAD_PRIORITY_NORMAL

constexpr

Initial value:

=
  SDL_THREAD_PRIORITY_NORMAL

THREAD_PRIORITY_TIME_CRITICAL

constexpr ThreadPriority SDL::THREAD_PRIORITY_TIME_CRITICAL

constexpr

Initial value:

=
  SDL_THREAD_PRIORITY_TIME_CRITICAL

THREAD_UNKNOWN

constexpr ThreadState SDL::THREAD_UNKNOWN

constexpr

Initial value:

=
  SDL_THREAD_UNKNOWN