Semi-safe reference for Thread.

Inheritance diagram for SDL::ThreadRef:

Collaboration diagram for SDL::ThreadRef:

Public Member Functions
	ThreadRef (ThreadParam resource) noexcept
	Constructs from ThreadParam. More...

	ThreadRef (ThreadRaw resource) noexcept
	Constructs from ThreadParam. More...

constexpr	ThreadRef (const ThreadRef &other) noexcept=default
	Copy constructor.

	~ThreadRef ()
	Destructor.

constexpr	Thread (std::nullptr_t=nullptr) noexcept
	Default ctor.

constexpr	Thread (const ThreadRaw resource) noexcept
	Constructs from ThreadParam. More...

constexpr	Thread (const Thread &other) noexcept=default
	Copy constructor.

constexpr	Thread (Thread &&other) noexcept
	Move constructor.

constexpr	Thread (const ThreadRef &other)=delete

constexpr	Thread (ThreadRef &&other)=delete

	Thread (ThreadCB fn, StringParam name)
	Default ctor.

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

	Thread (PropertiesParam props)
	Create a new thread with with the specified properties. More...

Public Member Functions inherited from SDL::Thread
constexpr	Thread (std::nullptr_t=nullptr) noexcept
	Default ctor.

constexpr	Thread (const ThreadRaw resource) noexcept
	Constructs from ThreadParam. More...

constexpr	Thread (Thread &&other) noexcept
	Move constructor.

constexpr	Thread (const ThreadRef &other)=delete

constexpr	Thread (ThreadRef &&other)=delete

	Thread (ThreadCB fn, StringParam name)
	Default ctor.

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

	Thread (PropertiesParam props)
	Create a new thread with with the specified properties. More...

	~Thread ()
	Destructor.

constexpr Thread &	operator= (Thread &&other) noexcept
	Assignment operator.

constexpr ThreadRaw	get () const noexcept
	Retrieves underlying ThreadRaw.

constexpr ThreadRaw	release () noexcept
	Retrieves underlying ThreadRaw and clear this.

constexpr auto	operator<=> (const Thread &other) const noexcept=default
	Comparison.

constexpr	operator bool () const noexcept
	Converts to bool.

constexpr	operator ThreadParam () const noexcept
	Converts to ThreadParam.

void	Detach ()
	Let a thread clean up on exit without intervention. More...

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

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

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

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

Additional Inherited Members
Static Public Member Functions inherited from SDL::Thread
static void	SetCurrentPriority (ThreadPriority priority)
	Set the priority for the current thread. More...

Protected Member Functions inherited from SDL::Thread
constexpr	Thread (const Thread &other) noexcept=default
	Copy constructor.

constexpr Thread &	operator= (const Thread &other) noexcept=default
	Assignment operator.

Constructor & Destructor Documentation

◆ ThreadRef() [1/2]

SDL::ThreadRef::ThreadRef ( ThreadParam resource )

inlinenoexcept

Parameters

resource a ThreadRaw or Thread.

This does not takes ownership!

◆ ThreadRef() [2/2]

SDL::ThreadRef::ThreadRef ( ThreadRaw resource )

inlinenoexcept

Parameters

resource a ThreadRaw or Thread.

This does not takes ownership!

Member Function Documentation

◆ Thread() [1/3]

constexpr SDL::Thread::Thread ( const ThreadRaw resource )

inlineexplicitconstexprnoexcept

Parameters

resource a ThreadRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

◆ Thread() [2/3]

SDL::Thread::Thread ( PropertiesParam 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 Thread.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 "Thread.Thread" 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: Thread.Thread; Thread.Wait

◆ Thread() [3/3]

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

inline

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

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

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.

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: Thread.Thread; Thread.Wait

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

SDL3pp/SDL3pp_thread.h

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ ThreadRef() [1/2]

◆ ThreadRef() [2/2]

Member Function Documentation

◆ Thread() [1/3]

◆ Thread() [2/3]

◆ Thread() [3/3]