SDL::ThreadRef Struct Reference

The SDL thread object. More...

Inheritance diagram for SDL::ThreadRef:

Public Member Functions
const char *	GetName () const
	Get the thread name as it was specified in (Thread.Create).
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 from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
Public Member Functions inherited from SDL::Resource< SDL_Thread * >
constexpr	Resource (SDL_Thread * resource={})
	Constructs from the underlying resource.
constexpr	Resource (const ResourceHandle< Resource< SDL_Thread * > > auto &resource)
	Constructs from pointer like.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
constexpr	operator bool () const
	True if contains a valid resource.
constexpr	operator value_type () const
	Converts back to underlying type.
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 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.
static void	reset (SDL_Thread *resource)
	Let a thread clean up on exit without intervention.

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_Thread * >
using	value_type = SDL_Thread *
	The raw resource type.

Detailed Description

These are opaque data.

Since

This datatype is available since SDL 3.2.0.

Category:

Resource

See also

Thread.Create

ThreadRef.Wait

Thread

Member Function Documentation

GetID()

ThreadID SDL::ThreadRef::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::ThreadRef::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::ThreadRef::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

reset()

static void SDL::ThreadRef::reset ( SDL_Thread *  resource )

inlinestatic

A thread may be "detached" to signify that it should not remain until another thread has called ThreadRef.Wait() 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 ThreadRef.Wait().

Once a thread is detached, you should usually assume the ThreadRef 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 ThreadRef.Wait() 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 Thread.Detach(), it will stop waiting for a call to ThreadRef.Wait() and clean up immediately. It is not safe to detach a thread that might be used with ThreadRef.Wait().

You may not call ThreadRef.Wait() 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 nullptr to this function; it is a no-op.

Parameters

resource

the ThreadRef pointer that was returned from the Thread.Create() call that started this thread.

Since

This function is available since SDL 3.2.0.

See also

Thread.Create

ThreadRef.Wait

SetCurrentPriority()

static void SDL::ThreadRef::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::ThreadRef::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 ThreadRef that references it becomes invalid and should not be referenced again. As such, only one thread may call ThreadRef.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.

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

Thread.Create

Thread.Detach

---

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

• SDL3pp/SDL3pp_thread.h