Handle to an owned thread. More...

Inheritance diagram for SDL::Thread:

[legend]

Public Member Functions
void	Detach ()
	Let a thread clean up on exit without intervention.

ThreadShared	share ()
	Move this thread into a ThreadShared.

constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DELETER deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

Public Member Functions inherited from SDL::ResourceUnique< ThreadRef >
constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DefaultDeleter< ThreadRef > deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

	~ResourceUnique ()
	Destructor.

constexpr ResourceUnique &	operator= (ResourceUnique other)
	Assignment operator.

void	reset ()
	Resets the value, destroying the resource if not nullptr.

Public Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
RESOURCE	release ()
	Returns reference and reset this.

Public Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	operator bool () const
	Check if not null.

constexpr bool	operator== (const ResourcePtrBase &other) const
	Comparison.

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

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

constexpr reference	operator* () const
	Gets reference.

constexpr const reference *	operator-> () const
	Gets addressable reference.

constexpr reference *	operator-> ()
	Gets addressable reference.

reference	get () const
	Get reference.

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

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

static Thread	CreateWithProperties (PropertiesRef props)
	Create a new thread with with the specified properties.

Additional Inherited Members
Public Types inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
using	deleter = DELETER
	The deleter type.

Public Types inherited from SDL::ResourcePtrBase< RESOURCE >
using	reference = RESOURCE
	The reference resource type.

using	value_type = typename reference::value_type
	The raw resource type.

Protected Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
constexpr	ResourceOwnerBase (base::value_type value={}, DELETER deleter={})
	Constructs from raw type.

void	free ()
	Frees resource.

Protected Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	ResourcePtrBase (value_type value={})
	Constructs from raw type.

reference &	get ()
	Get reference.

Detailed Description

Category:: Resource

See also: ThreadRef

Member Function Documentation

◆ Create() [1/2]

static Thread SDL::Thread::Create	(	ThreadCB	fn,
		StringParam	name
	)

inlinestatic

Parameters

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

Returns: 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.CreateWithProperties; ThreadRef.Wait

◆ Create() [2/2]

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

inlinestatic

This is a convenience function, equivalent to calling Thread.CreateWithProperties 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`.

Returns: 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.CreateWithProperties; ThreadRef.Wait

◆ CreateWithProperties()

static Thread SDL::Thread::CreateWithProperties ( PropertiesRef props )

inlinestatic

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 ThreadRef.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.CreateWithProperties" 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.

Returns: 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.Create; ThreadRef.Wait

◆ Detach()

void SDL::Thread::Detach ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Thread.Create; ThreadRef.Wait

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

SDL3pp/SDL3pp_thread.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Create() [1/2]

◆ Create() [2/2]

◆ CreateWithProperties()

◆ Detach()