#include <thread.h>

Public Types
using	native_handle_type = backend::NativeThreadHandle

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

Public Member Functions
	Thread ()

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

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

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

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

Thread &	operator= (Thread &&other)

	~Thread ()

	Thread (const Thread &)=delete

	Thread (Thread &&)=delete

Thread &	operator= (const Thread &)=delete

id	get_id () const

bool	joinable () const

template<typename... , bool kJoiningEnabled = false>
void	join ()

void	detach ()

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

native_handle_type	native_handle ()

Detailed Description

The class Thread can represent a single thread of execution. Threads allow multiple functions to execute concurrently.

Threads may begin execution immediately upon construction of the associated thread object (pending any OS scheduling delays), starting at the top-level function provided as a constructor argument. The return value of the top-level function is ignored. The top-level function may communicate its return value by modifying shared variables (which may require synchronization, see pw_sync and std::atomic)

Thread objects may also be in the state that does not represent any thread (after default construction, move from, detach, or join), and a thread of execution may be not associated with any thread objects (after detach).

No two Thread objects may represent the same thread of execution; Thread is not CopyConstructible or CopyAssignable, although it is MoveConstructible and MoveAssignable.

Member 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_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.

Constructor & Destructor Documentation

◆ 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.

Member 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.

◆ 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.

◆ 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.

◆ 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.

◆ operator=()

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

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

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

pw_thread/public/pw_thread/thread.h

Public Types

Public Member Functions