Oveview

Main docs: https://pigweed.dev/pw_thread.

Namespaces
namespace	pw::thread
	Thread creation and execution library.

Classes
class	pw::ThreadAttrs

class	pw::ThreadChecker

class	pw::LazyInitThreadChecker

class	pw::ThreadContext< kStackSizeBytes >

class	pw::ThreadContext< kExternallyAllocatedThreadStack >

class	pw::ThreadContextFor< kAttributes >

class	pw::thread::Options

class	pw::ThreadStack< kStackSizeBytes >

class	pw::thread::test::TestThreadContext

class	pw::thread::Thread

Typedefs
using	pw::DefaultThreadContext = ThreadContext< thread::backend::kDefaultStackSizeBytes >
	Alias for ThreadContext with the backend's default stack size.

using	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::native_type = T

using	pw::ThreadPriority = thread::internal::Priority< thread::backend::PriorityType, thread::backend::kLowestPriority, thread::backend::kHighestPriority, thread::backend::kDefaultPriority >

using	pw::internal::ThreadStackPointer = decltype(std::declval< thread::backend::Stack< 0 > >().data())

using	pw::ThreadStack< kStackSizeBytes >::native = internal::ThreadStackPointer

using	pw::thread::Thread::native_handle_type = backend::NativeThreadHandle

using	pw::thread::Thread::id = ::pw::thread::backend::NativeId

using	pw::Thread = ::pw::thread::Thread

Functions
constexpr	pw::ThreadAttrs::ThreadAttrs ()
	Initializes attributes to their backend-defined defaults.

constexpr	pw::ThreadAttrs::ThreadAttrs (const ThreadAttrs &)=default
	Thread attributes can be copied to share properties between threads.

constexpr ThreadAttrs &	pw::ThreadAttrs::operator= (const ThreadAttrs &)=default

constexpr const char *	pw::ThreadAttrs::name () const
	Name hint as a null-terminated string. Never null.

constexpr ThreadAttrs &	pw::ThreadAttrs::set_name (const char *name)

constexpr ThreadAttrs &	pw::ThreadAttrs::set_name (std::nullptr_t)=delete

constexpr ThreadPriority	pw::ThreadAttrs::priority () const

constexpr ThreadAttrs &	pw::ThreadAttrs::set_priority (ThreadPriority priority)
	Sets a thread priority hint.

constexpr auto	pw::ThreadAttrs::native_stack () const

constexpr auto	pw::ThreadAttrs::native_stack_pointer () const

constexpr auto	pw::ThreadAttrs::native_stack_size () const

constexpr size_t	pw::ThreadAttrs::stack_size_bytes () const
	Returns the size of the stack in bytes.

constexpr ThreadAttrs &	pw::ThreadAttrs::set_stack_size_bytes (size_t stack_size_bytes)

template<size_t kStackSizeBytes>
constexpr ThreadAttrs &	pw::ThreadAttrs::set_stack (ThreadStack< kStackSizeBytes > &stack)

constexpr ThreadAttrs &	pw::ThreadAttrs::clear_stack ()
	Clears a previous call to `set_stack`.

constexpr bool	pw::ThreadAttrs::has_external_stack () const

	pw::ThreadChecker::ThreadChecker (Thread::id id)

void	pw::ThreadChecker::lock ()

void	pw::ThreadChecker::unlock ()

void	pw::LazyInitThreadChecker::lock ()

void	pw::LazyInitThreadChecker::unlock ()

	pw::ThreadContext< kStackSizeBytes >::ThreadContext (const ThreadContext &)=delete

ThreadContext &	pw::ThreadContext< kStackSizeBytes >::operator= (const ThreadContext &)=delete

constexpr thread::backend::NativeContextWithStack< kStackSizeBytes > &	pw::ThreadContext< kStackSizeBytes >::native ()

	pw::ThreadContext< kExternallyAllocatedThreadStack >::ThreadContext (const ThreadContext &)=delete

ThreadContext &	pw::ThreadContext< kExternallyAllocatedThreadStack >::operator= (const ThreadContext &)=delete

constexpr thread::backend::NativeContext &	pw::ThreadContext< kExternallyAllocatedThreadStack >::native ()

	pw::ThreadContextFor< kAttributes >::ThreadContextFor (const ThreadContextFor &)=delete

ThreadContextFor &	pw::ThreadContextFor< kAttributes >::operator= (const ThreadContextFor &)=delete

constexpr auto &	pw::ThreadContextFor< kAttributes >::native ()

template<typename T >
PW_CONSTEVAL std::array< T, kNamedPriorities >	pw::thread::internal::PriorityOffsets (T highest)

constexpr bool	pw::thread::internal::operator>= (AbstractLevel rhs) const

constexpr AbstractLevel	pw::thread::internal::operator+ (U amount) const

constexpr AbstractLevel	pw::thread::internal::operator- (U amount) const

static constexpr bool	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::IsSupported ()
	True if the `pw_thread` backend supports more than one priority level.

constexpr	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Priority ()
	Constructs a priority at the backend-specified default level.

constexpr	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Priority (const Priority &)=default

constexpr Priority &	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::operator= (const Priority &)=default

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Lowest ()

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::VeryLow ()
	Priority higher than `Lowest`, but lower than `Low`, if possible.

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Low ()
	Priority higher than `VeryLow`, but lower than `MediumLow`, if possible.

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::MediumLow ()
	Priority higher than `Low`, but lower than `Medium`, if possible.

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Medium ()

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::MediumHigh ()
	Priority higher than `Medium`, but lower than `High`, if possible.

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::High ()
	Priority higher than `MediumHigh`, but lower than `VeryHigh`, if possible.

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::VeryHigh ()
	Priority higher than `High`, but lower than `Highest`, if possible.

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Highest ()

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Default ()
	Returns a priority at the backend-specified default level.

constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::NextHigher (Priority maximum=Highest()) const

constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::NextLower (Priority minimum=Lowest()) const

constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::NextLowerClamped (Priority minimum=Lowest()) const
	Returns the next lower priority, down to the provided maximum.

constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::NextHigherClamped (Priority maximum=Highest()) const
	Returns the next higher priority, up to the provided minimum.

constexpr bool	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::operator== (Priority rhs) const

constexpr bool	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::operator!= (Priority rhs) const

constexpr bool	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::operator< (Priority rhs) const

constexpr bool	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::operator<= (Priority rhs) const

constexpr bool	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::operator> (Priority rhs) const

constexpr bool	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::operator>= (Priority rhs) const

constexpr native_type	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::native () const

static constexpr Priority	pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::FromNative (native_type priority)

template<typename T >
constexpr auto	pw::internal::ThreadStackSpan (T *pointer, size_t size)

constexpr auto	pw::internal::NativeStackSizeBytes (size_t size)

constexpr native	pw::ThreadStack< kStackSizeBytes >::native_pointer ()

constexpr size_t	pw::ThreadStack< kStackSizeBytes >::native_size () const

	pw::thread::test::TestThreadContext::TestThreadContext (const TestThreadContext &)=delete

TestThreadContext &	pw::thread::test::TestThreadContext::operator= (const TestThreadContext &)=delete

const Options &	pw::thread::test::TestThreadContext::options () const

	pw::thread::Thread::Thread ()

	pw::thread::Thread::Thread (const Options &options, Function< void()> &&entry)

template<const ThreadAttrs & kAttributes>
	pw::thread::Thread::Thread (ThreadContextFor< kAttributes > &context, Function< void()> &&entry)

template<size_t kStackSizeHintBytes>
	pw::thread::Thread::Thread (ThreadContext< kStackSizeHintBytes > &context, const ThreadAttrs &attributes, Function< void()> &&entry)

	pw::thread::Thread::Thread (ThreadContext<> &context, const ThreadAttrs &attributes, Function< void()> &&entry)

Thread &	pw::thread::Thread::operator= (Thread &&other)

	pw::thread::Thread::~Thread ()

	pw::thread::Thread::Thread (const Thread &)=delete

	pw::thread::Thread::Thread (Thread &&)=delete

Thread &	pw::thread::Thread::operator= (const Thread &)=delete

id	pw::thread::Thread::get_id () const

bool	pw::thread::Thread::joinable () const

template<typename... , bool kJoiningEnabled = false>
void	pw::thread::Thread::join ()

void	pw::thread::Thread::detach ()

void	pw::thread::Thread::swap (Thread &other)
	Exchanges the underlying handles of two thread objects.

native_handle_type	pw::thread::Thread::native_handle ()

Variables
constexpr size_t	pw::kExternallyAllocatedThreadStack

constexpr size_t	pw::thread::internal::kNamedPriorities = 9

template<typename T , T kLowest, T kHighest, bool = kLowest <= kHighest>
AbstractLevel rhs	pw::thread::internal::const { return n_ < rhs.n_

Typedef Documentation

◆ id

using pw::thread::Thread::id = ::pw::thread::backend::NativeId

The class id is a lightweight, trivially copyable class that serves as a unique identifier of Thread objects.

Instances of this class may also hold the special distinct value that does not represent any thread. Once a thread has finished, the value of its Thread::id may be reused by another thread.

This class is designed for use as key in associative containers, both ordered and unordered.

The backend must ensure that:

There is a default construct which does not represent a thread.
Compare operators (==, !=, <, <=, >, >=) are provided to compare and sort IDs.

◆ native

template<size_t kStackSizeBytes>

using pw::ThreadStack< kStackSizeBytes >::native = internal::ThreadStackPointer

Native stack "element". Operating systems typically accept a pointer to this type in their thread creation APIs. May be void for APIs that take a void*, such as pthread_attr_setstack().

◆ native_handle_type

using pw::thread::Thread::native_handle_type = backend::NativeThreadHandle

The type of the native handle for the thread. As with std::thread, use is inherently non-portable.

◆ native_type

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

using pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::native_type = T

Alias for the native priority type used by the backend.

Warning: Using native_type is not portable!

◆ Thread

using pw::Thread = typedef ::pw::thread::Thread

pw::thread::Thread will be renamed to pw::Thread. New code should refer to pw::Thread.

◆ ThreadPriority

using pw::ThreadPriority = typedef thread::internal::Priority<thread::backend::PriorityType, thread::backend::kLowestPriority, thread::backend::kHighestPriority, thread::backend::kDefaultPriority>

Represents a thread's priority. Schedulers favor higher priority tasks when determining which thread to run. Scheduling policies differ, but a common default policy for real-time operating systems is preemptive scheduling, where the highest priority ready thread is always selected to run. If there are multiple tasks with the same priority, RTOSes may use round-robin scheduling, where each ready thread at a given priority is given equal opportunity to run.

Priorities may be compared with ==, !=, <, etc. Comparisons occur in terms of the native priorities they represent, but are translated such that logically lower priorities always compare as less than higher priorities, even if the underlying RTOS uses lower numbers for higher priorities.

Function Documentation

◆ detach()

void pw::thread::Thread::detach ( )

Separates the thread of execution from the thread object, allowing execution to continue independently. Any allocated resources will be freed once the thread exits.

Precondition: The thread must have been NEITHER detached nor joined.

Postcondition: After calling detach *this no longer owns any thread.

◆ FromNative()

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

static constexpr Priority pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::FromNative ( native_type priority )

inlinestaticconstexpr

Returns the priority value used to represent this native priority.

Warning: This function is not portable!

◆ get_id()

id pw::thread::Thread::get_id ( ) const

Returns a value of Thread::id identifying the thread associated with *this. If there is no thread associated, default constructed Thread::id is returned.

◆ has_external_stack()

constexpr bool pw::ThreadAttrs::has_external_stack ( ) const

inlineconstexpr

True if the ThreadAttrs use an externally allocated stack, rather than one integrated with the ThreadContext.

◆ Highest()

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

static constexpr Priority pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Highest ( )

inlinestaticconstexpr

Returns the highest priority supported by the backend. The underlying OS may support higher priorities; backends may only expose a subset of priorities.

◆ joinable()

bool pw::thread::Thread::joinable ( ) const

inline

Checks if the Thread object identifies an active thread of execution which has not yet been detached. Specifically, returns true if get_id() != pw::Thread::id() and detach() has NOT been invoked. So a default constructed thread is not joinable and neither is one which was detached.

A thread that has not started or has finished executing code which was never detached, but has not yet been joined is still considered an active thread of execution and is therefore joinable.

◆ Lowest()

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

static constexpr Priority pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Lowest ( )

inlinestaticconstexpr

Returns the lowest priority supported by the backend. The underlying OS may support lower priorities; backends may only expose a subset of priorities.

◆ Medium()

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

static constexpr Priority pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::Medium ( )

inlinestaticconstexpr

Priority higher than MediumLow, but lower than MediumHigh, if possible.

◆ native()

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

constexpr native_type pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::native ( ) const

inlineconstexpr

Returns the native value used to represent this priority.

Warning: This function is not portable!

◆ native_handle()

native_handle_type pw::thread::Thread::native_handle ( )

Returns the native handle for the thread. As with std::thread, use is inherently non-portable.

◆ native_pointer()

template<size_t kStackSizeBytes>

constexpr native pw::ThreadStack< kStackSizeBytes >::native_pointer ( )

inlineconstexpr

Returns a pointer to the native stack.

Warning: Calling this function is not portable.

◆ native_size()

template<size_t kStackSizeBytes>

constexpr size_t pw::ThreadStack< kStackSizeBytes >::native_size ( ) const

inlineconstexpr

Returns the size of the stack in terms of the native units – NOT necessarily bytes!

Warning: Calling this function is not portable.

◆ native_stack()

constexpr auto pw::ThreadAttrs::native_stack ( ) const

inlineconstexpr

Returns a span of the native stack to use for this thread. The stack may not be in terms of bytes! Backends that use void* for stacks return a std::byte span. If the backend doesn't support user-specified stacks,

This function is NOT constexpr if the backend uses void* for stacks.

◆ native_stack_pointer()

constexpr auto pw::ThreadAttrs::native_stack_pointer ( ) const

inlineconstexpr

Returns a pointer to the native stack to use for this thread.

Warning: This function is NOT portable!

◆ native_stack_size()

constexpr auto pw::ThreadAttrs::native_stack_size ( ) const

inlineconstexpr

Returns the size of the stack in native units (not necessarily bytes), using the native type (typically an unsigned integer).

Warning: This function is NOT portable!

◆ NextHigher()

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

constexpr Priority pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::NextHigher ( Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority > maximum = Highest() ) const

inlineconstexpr

Returns the next higher priority. Fails if this priority is the maximum priority.

Warning: This function is not portable, since it fails on platforms that cannot represent the requested priority.

◆ NextLower()

template<typename T , T kLowestPriority, T kHighestPriority, T kDefaultPriority>

constexpr Priority pw::thread::internal::Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority >::NextLower ( Priority< T, kLowestPriority, kHighestPriority, kDefaultPriority > minimum = Lowest() ) const

inlineconstexpr

Returns the next lower priority. Fails if this priority is the minimum priority.

Warning: This function is not portable, since it fails on platforms that cannot represent the requested priority.

◆ operator=()

Thread & pw::thread::Thread::operator= ( Thread && other )

Postcondition: The other thread no longer represents a thread of execution.

◆ options()

const Options & pw::thread::test::TestThreadContext::options ( ) const

inline

pw::thread::test::TestThreadContext returns a pw::thread::Options associated with the this object, which can be used to contruct a thread.

Returns: The default options for testing thread.

◆ set_stack()

template<size_t kStackSizeBytes>

constexpr ThreadAttrs & pw::ThreadAttrs::set_stack ( ThreadStack< kStackSizeBytes > & stack )

inlineconstexpr

Sets the thread to use the provided stack, instead of a stack integrated into the ThreadContext.

◆ set_stack_size_bytes()

constexpr ThreadAttrs & pw::ThreadAttrs::set_stack_size_bytes ( size_t stack_size_bytes )

inlineconstexpr

Sets the thread stack size to use for a stack provided by the ThreadContext. If 0, the thread backend's minimum stack size is used.

Precondition: An external stack has not been set with set_stack().

◆ Thread() [1/2]

pw::thread::Thread::Thread ( )

Creates a new thread object which does not represent a thread of execution yet.

◆ Thread() [2/2]

pw::thread::Thread::Thread	(	const Options &	options,
		Function< void()> &&	entry
	)

Creates a thread from a void-returning function or lambda.

This function accepts any callable (including lambdas) which returns void. When using a lambda, the captures must not exceed the inline size of pw::Function (usually a single pointer) unless dynamic allocation is enabled.

To invoke a member method of a class a static lambda closure can be used to ensure the dispatching closure is not destructed before the thread is done executing. For example:

class Foo {
 public:
  void DoBar() {}
};
Foo foo;
 
// Now use the lambda closure as the thread entry, passing the foo's
// this as the argument.
Thread thread(options, [&foo]() { foo.DoBar(); });
thread.detach();

Postcondition: The thread get EITHER detached or joined.

◆ ~Thread()

pw::thread::Thread::~Thread ( )

Precondition: The thread must have been EITHER detached or joined.

Variable Documentation

◆ kExternallyAllocatedThreadStack

constexpr size_t pw::kExternallyAllocatedThreadStack

inlineconstexpr

Initial value:

=

std::numeric_limits<size_t>::max()

Oveview

Namespaces

Classes

Typedefs

Functions

Variables

Typedef Documentation

◆ id

◆ native

◆ native_handle_type

◆ native_type

◆ Thread

◆ ThreadPriority

Function Documentation

◆ detach()

◆ FromNative()

◆ get_id()

◆ has_external_stack()

◆ Highest()

◆ joinable()

◆ Lowest()

◆ Medium()

◆ native()

◆ native_handle()

◆ native_pointer()

◆ native_size()

◆ native_stack()

◆ native_stack_pointer()

◆ native_stack_size()

◆ NextHigher()

◆ NextLower()

◆ operator=()

◆ options()

◆ set_stack()

◆ set_stack_size_bytes()

◆ Thread() [1/2]

◆ Thread() [2/2]

◆ ~Thread()

Variable Documentation

◆ kExternallyAllocatedThreadStack