The SDL thread object. More...

Inheritance diagram for SDL::ThreadBase:

[legend]

Public Member Functions
	ThreadBase (ThreadCB fn, StringParam name)
	Create a new thread with a default stack size.

	ThreadBase (ThreadFunction fn, StringParam name, void *data)
	Create a new thread with a default stack size.

	ThreadBase (PropertiesBase &props)
	Create a new thread with with the specified properties.

const char *	GetName () const
	Get the thread name as it was specified in ThreadBase.ThreadBase().

ThreadID	GetID () const
	Get the thread identifier for the specified thread.

void	Wait (int *status)
	Wait for a thread to finish.

ThreadState	GetState () const
	Get the current state of a thread.

constexpr	Resource (T resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Public Member Functions inherited from SDL::Resource< SDL_Thread * >
constexpr	Resource (SDL_Thread * resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

constexpr	operator bool () const
	True if contains a valid resource.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_Thread *	get () const
	Return contained resource;.

constexpr SDL_Thread *	release (SDL_Thread * newResource={})
	Return contained resource and empties or replace value.

constexpr const SDL_Thread *	operator-> () const
	Access to fields.

constexpr SDL_Thread *	operator-> ()
	Access to fields.

Static Public Member Functions
static void	SetCurrentPriority (ThreadPriority priority)
	Set the priority for the current thread.

Detailed Description

These are opaque data.

Since: This datatype is available since SDL 3.2.0.

See also: ThreadBase.ThreadBase; ThreadBase.Wait

Category:: Resource

See also: Thread; ThreadRef

Constructor & Destructor Documentation

◆ ThreadBase() [1/3]

SDL::ThreadBase::ThreadBase	(	ThreadCB	fn,
		StringParam	name
	)

inline

Parameters

fn	the ThreadFunction function to call in the new thread.
name	the name of the thread.

Postcondition: an opaque pointer to the new thread object on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: ThreadBase.ThreadBase; ThreadBase.Wait

◆ ThreadBase() [2/3]

SDL::ThreadBase::ThreadBase	(	ThreadFunction	fn,
		StringParam	name,
		void *	data
	)

inline

This is a convenience function, equivalent to calling ThreadBase.ThreadBase with the following properties set:

prop::thread.CREATE_ENTRY_FUNCTION_POINTER: fn
prop::thread.CREATE_NAME_STRING: name
prop::thread.CREATE_USERDATA_POINTER: data

Usually, apps should just call this function the same way on every platform and let the macros hide the details.

Parameters

fn	the ThreadFunction function to call in the new thread.
name	the name of the thread.
data	a pointer that is passed to `fn`.

Postcondition: an opaque pointer to the new thread object on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: ThreadBase.ThreadBase; ThreadBase.Wait

◆ ThreadBase() [3/3]

SDL::ThreadBase::ThreadBase ( PropertiesBase & props )

inline

These are the supported properties:

prop::thread.CREATE_ENTRY_FUNCTION_POINTER: an ThreadFunction value that will be called at the start of the new thread's life. Required.
prop::thread.CREATE_NAME_STRING: the name of the new thread, which might be available to debuggers. Optional, defaults to nullptr.
prop::thread.CREATE_USERDATA_POINTER: an arbitrary app-defined pointer, which is passed to the entry function on the new thread, as its only parameter. Optional, defaults to nullptr.
prop::thread.CREATE_STACKSIZE_NUMBER: the size, in bytes, of the new thread's stack. Optional, defaults to 0 (system-defined default).

SDL makes an attempt to report prop::thread.CREATE_NAME_STRING to the system, so that debuggers can display it. Not all platforms support this.

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:

https://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 ThreadBase.GetName().

The size (in bytes) of the new stack can be specified with prop::thread.CREATE_STACKSIZE_NUMBER. Zero means "use the system default" which might be wildly different between platforms. x86 Linux generally defaults to eight megabytes, an embedded device might be a few kilobytes instead. You generally need to specify a stack that is a multiple of the system's page size (in many cases, this is 4 kilobytes, but check your system documentation).

Note that this "function" is actually a macro that calls an internal function with two extra parameters not listed here; they are hidden through preprocessor macros and are needed to support various C runtimes at the point of the function call. Language bindings that aren't using the C headers will need to deal with this.

The actual symbol in SDL is SDL_CreateThreadWithPropertiesRuntime, so there is no symbol clash, but trying to load an SDL shared library and look for "ThreadBase.ThreadBase" will fail.

Usually, apps should just call this function the same way on every platform and let the macros hide the details.

Parameters

props the properties to use.

Postcondition: an opaque pointer to the new thread object on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: ThreadBase.ThreadBase; ThreadBase.Wait

Member Function Documentation

◆ GetID()

ThreadID SDL::ThreadBase::GetID ( ) const

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.

Returns: the ID of the specified thread, or the ID of the current thread if thread is nullptr.

Since: This function is available since SDL 3.2.0.

See also: GetCurrentThreadID

◆ GetName()

const char * SDL::ThreadBase::GetName ( ) const

inline

Returns: a pointer to a UTF-8 string that names the specified thread, or nullptr if it doesn't have a name.

Since: This function is available since SDL 3.2.0.

◆ GetState()

ThreadState SDL::ThreadBase::GetState ( ) const

inline

Returns: the current state of a thread, or THREAD_UNKNOWN if the thread isn't valid.

Since: This function is available since SDL 3.2.0.

See also: ThreadState

◆ SetCurrentPriority()

static void SDL::ThreadBase::SetCurrentPriority ( ThreadPriority priority )

inlinestatic

Note that some platforms will not let you alter the priority (or at least, promote the thread to a higher priority) at all, and some require you to be an administrator account. Be prepared for this to fail.

Parameters

priority the ThreadPriority to set.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ Wait()

void SDL::ThreadBase::Wait ( int * status )

inline

Threads that haven't been detached will remain until this function cleans them up. Not doing so is a resource leak.

Once a thread has been cleaned up through this function, the ThreadBase that references it becomes invalid and should not be referenced again. As such, only one thread may call ThreadBase.Wait() on another.

The return code from the thread function is placed in the area pointed to by status, if status is not nullptr.

You may not wait on a thread that has been used in a call to ThreadRef.Detach(). Use either that function or this one, but not both, or behavior is undefined.

It is safe to pass a nullptr thread to this function; it is a no-op.

Note that the thread pointer is freed by this function and is not valid afterward.

          ThreadBase.ThreadBase() call that started this thread.

Parameters

status a pointer filled in with the value returned from the thread function by its 'return', or -1 if the thread has been detached or isn't valid, may be nullptr.

Since: This function is available since SDL 3.2.0.

See also: ThreadBase.ThreadBase; ThreadRef.Detach

The documentation for this struct was generated from the following file:

SDL3pp/SDL3pp_thread.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ThreadBase() [1/3]

◆ ThreadBase() [2/3]

◆ ThreadBase() [3/3]

Member Function Documentation

◆ GetID()

◆ GetName()

◆ GetState()

◆ SetCurrentPriority()

◆ Wait()