Overview

A thread class, modeled after std::thread.

This class is similar to std::thread, with the key advantage that it will work on any threaded platform that EtcPal is ported for, including the embedded RTOS platforms. If your application or library does not need to run on these platforms, consider using std::thread instead.

There are a few differences from std::thread:

The thread is automatically joined on destruction (this matches the behavior of C++20's std::jthread)
The thread is not detachable; that is, once created, it must be joined before it is destroyed in all cases.
The thread has a Start() function - a previously default-constructed thread can be assigned some operation parameters, then started, without being reassigned to another instance.

This is one of the few EtcPal wrappers that does heap allocation, as the thread function and arguments need to be stored.

Public Member Functions
	Thread ()=default
	Create a new thread object which does not yet represent a thread.

template<class Function , class... Args, typename std::enable_if<!std::is_arithmetic< Function >::value, bool >::type = true>
	Thread (Function &&func, Args &&... args)
	Create a new thread object and associate it with a new thread of execution. More...

	Thread (unsigned int priority, unsigned int stack_size, const char name, void platform_data=nullptr)
	Create a new thread object which does not yet represent a thread, passing explicit parameters. More...

virtual	~Thread ()
	Destroy the thread object. More...

	Thread (Thread &&other) noexcept
	Move another thread into this thread. More...

Thread &	operator= (Thread &&other) noexcept
	Move another thread into this thread. More...

	Thread (const Thread &other)=delete
	Deleted copy constructor - threads are not copyable.

Thread &	operator= (const Thread &other)=delete
	Deleted copy assignment operator - threads are not copyable.

bool	joinable () const noexcept
	Whether the thread object identifies an active thread of execution.

template<class Function , class... Args>
Error	Start (Function &&func, Args &&... args)
	Associate this thread object with a new thread of execution. More...

Error	Join (int timeout_ms=ETCPAL_WAIT_FOREVER) noexcept
	Wait for the thread to finish execution. More...

Error	Terminate () noexcept
	Forcefully kill the thread. More...

Getters
unsigned int	priority () const noexcept
	Get the priority of this thread (not valid on all platforms).

unsigned int	stack_size () const noexcept
	Get the stack size of this thread in bytes (not valid on all platforms).

const char *	name () const noexcept
	Get the name of this thread.

void *	platform_data () const noexcept
	Get the platform-specific data of this thread.

const EtcPalThreadParams &	params () const noexcept
	Get a reference the parameters of this thread.

etcpal_thread_os_handle_t	os_handle () const noexcept
	Get the native OS handle of this thread. More...

Setters
Thread &	SetPriority (unsigned int priority) noexcept
	Set the priority of this thread. More...

Thread &	SetStackSize (unsigned int stack_size) noexcept
	Set the stack size of this thread in bytes. More...

Thread &	SetName (const char *name) noexcept
	Set the name of this thread. More...

Thread &	SetName (const std::string &name) noexcept
	Set the name of this thread. More...

Thread &	SetPlatformData (void *platform_data) noexcept
	Set the platform-specific parameter data. More...

Thread &	SetParams (const EtcPalThreadParams &params) noexcept
	Set this thread's parameters from an existing EtcPalThreadParams struct. More...

Static Public Member Functions
static void	Sleep (unsigned int ms) noexcept
	Blocks the current thread for the specified number of milliseconds.

template<typename Rep , typename Period >
static void	Sleep (const std::chrono::duration< Rep, Period > &sleep_duration) noexcept
	Blocks the current thread for the specified duration. More...

Constructor & Destructor Documentation

◆ Thread() [1/3]

Thread	(	Function &&	func,
		Args &&...	args
	)

Create a new thread object and associate it with a new thread of execution.

Default thread parameters will be used. See the Start() function for more information.

Parameters

func	Callable object to execute in the new thread.
args	Arguments to pass to func.

Exceptions

std::runtime_error if Start() returns an error code.

Postcondition: joinable() == true

◆ Thread() [2/3]

Thread	(	unsigned int	priority,
		unsigned int	stack_size,
		const char *	name,
		void *	platform_data = `nullptr`
	)

inline

Create a new thread object which does not yet represent a thread, passing explicit parameters.

The thread is not running until Start() is called.

Parameters

priority	Priority of the thread.
stack_size	Stack size of the thread in bytes.
name	A name for the thread, maximum length ETCPAL_THREAD_NAME_MAX_LENGTH.
platform_data	Pointer to a platform-specific parameter structure. See EtcPalThreadParams for more information.

◆ ~Thread()

~Thread ( )

inlinevirtual

Destroy the thread object.

If *this has a valid associated thread (joinable() == true), the thread is joined before the destructor finishes.

◆ Thread() [3/3]

Thread ( Thread && other )

inlinenoexcept

Move another thread into this thread.

If *this has a valid associated thread (joinable() == true), the behavior is undefined. After this call, *this has the parameters of other, and other is set to a default-constructed state.

Member Function Documentation

◆ Join()

Error Join ( int timeout_ms = ETCPAL_WAIT_FOREVER )

inlinenoexcept

Wait for the thread to finish execution.

If timeout_ms is not given, or if ETCPAL_THREAD_HAS_TIMED_JOIN is false on this platform, blocks until the thread has exited. Otherwise, blocks up to timeout_ms waiting for the thread to exit.

Parameters

timeout_ms How long to wait for the thread to exit (default forever).

Returns: kEtcPalErrOk: The thread was stopped; joinable() is now false.; kEtcPalErrTimedOut: The thread did not join within the specified timeout.; kEtcPalErrInvalid: The thread was not running (joinable() == false).; Other codes translated from system error codes are possible.

◆ operator=()

Thread & operator= ( Thread && other )

inlinenoexcept

Move another thread into this thread.

If *this has a valid associated thread (joinable() == true), the behavior is undefined. After this call, *this has the parameters of other, and other is set to a default-constructed state.

◆ os_handle()

etcpal_thread_os_handle_t os_handle ( ) const

inlinenoexcept

Get the native OS handle of this thread.

Returns: The thread's OS handle, or ETCPAL_THREAD_OS_HANDLE_INVALID if the thread is not running (joinable() == false).

◆ SetName() [1/2]

Thread & SetName ( const char * name )

inlinenoexcept

Set the name of this thread.

This function does not have any effect on the associated thread unless it is called on a default-constructed thread before Start() is called. The pointer passed to this function must remain valid until after Start() is called.

Parameters

name	Name to set.

Returns: A reference to this thread, for method chaining.

◆ SetName() [2/2]

Thread & SetName ( const std::string & name )

inlinenoexcept

Set the name of this thread.

This function does not have any effect on the associated thread unless it is called on a default-constructed thread before Start() is called. The string reference passed to this function must remain valid until after Start() is called.

Parameters

name	Name to set.

Returns: A reference to this thread, for method chaining.

◆ SetParams()

Thread & SetParams ( const EtcPalThreadParams & params )

inlinenoexcept

Set this thread's parameters from an existing EtcPalThreadParams struct.

This function does not have any effect on the associated thread unless it is called on a default-constructed thread before Start() is called.

Parameters

params EtcPalThreadParams to use when starting the thread.

Returns: A reference to this thread, for method chaining.

◆ SetPlatformData()

Thread & SetPlatformData ( void * platform_data )

inlinenoexcept

Set the platform-specific parameter data.

This function does not have any effect on the associated thread unless it is called on a default-constructed thread before Start() is called. The pointer passed to this function must remain valid until after Start() is called.

Parameters

platform_data Pointer to platform-specific data structure.

Returns: A reference to this thread, for method chaining.

◆ SetPriority()

Thread & SetPriority ( unsigned int priority )

inlinenoexcept

Set the priority of this thread.

Priority is not valid on all platforms. This function does not have any effect on the associated thread unless it is called on a default-constructed thread before Start() is called.

Parameters

priority Priority to set.

Returns: A reference to this thread, for method chaining.

◆ SetStackSize()

Thread & SetStackSize ( unsigned int stack_size )

inlinenoexcept

Set the stack size of this thread in bytes.

Stack size is not valid on all platforms. This function does not have any effect on the associated thread unless it is called on a default-constructed thread before Start() is called.

Parameters

stack_size Stack size to set.

Returns: A reference to this thread, for method chaining.

◆ Sleep()

void Sleep ( const std::chrono::duration< Rep, Period > & sleep_duration )

staticnoexcept

Blocks the current thread for the specified duration.

Note: Duration will be clamped to [0, UINT_MAX] milliseconds.

◆ Start()

Error Start	(	Function &&	func,
		Args &&...	args
	)

Associate this thread object with a new thread of execution.

The new thread of execution starts executing

std::invoke(decay_copy(std::forward<Function>(f)),

decay_copy(std::forward<Args>(args))...);

where decay_copy is defined as

template <class T>

std::decay<T>::type decay_copy(T&& v) { return std::forward<T>(v); }

Except that the calls to decay_copy are evaluated in the context of the caller, so that any exceptions thrown during evaluation and copying/moving of the arguments are thrown in the current thread, without starting the new thread.

Parameters

func	Callable object to execute in the new thread.
args	Arguments to pass to func.

Returns: kEtcPalErrOk: The thread started successfully, joinable() is now true.; kEtcPalErrNoMem: Allocation failed while starting thread.; kEtcPalErrInvalid: The thread was already running (joinable() == true).; Other codes translated from system error codes are possible.

◆ Terminate()

Error Terminate ( )

inlinenoexcept

Forcefully kill the thread.

Be careful when using this function. Depending on the state of a thread when it is terminated, shared resources or memory could not be freed, resulting in memory leaks or deadlocks.

Returns: kEtcPalErrOk: The thread was terminated; joinable() is now false.; kEtcPalErrInvalid: The thread was not running (joinable() == false).; Other codes translated from system error codes are possible.

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

include/etcpal/cpp/thread.h

Overview

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ Thread() [1/3]

◆ Thread() [2/3]

◆ ~Thread()

◆ Thread() [3/3]

Member Function Documentation

◆ Join()

◆ operator=()

◆ os_handle()

◆ SetName() [1/2]

◆ SetName() [2/2]

◆ SetParams()

◆ SetPlatformData()

◆ SetPriority()

◆ SetStackSize()

◆ Sleep()

◆ Start()

◆ Terminate()