Threads

This library implements a complete cooperative multi-threading system. The interface is identical to the standard Thread Support library introduced in C++11, with some additional extensions. These are listed on this page.

The primary difference is that the scheduling system is cooperative, which means you must regularly call yield() to allow other threads to execute. A good opportunity to do so is while waiting for external events.

Header <thread>

Fully implemented in <jw/thread.h>

Class thread

thread::thread(std::size_t, ...)

An additional constructor is provided to specify the stack size.

void thread::abort()

Attempts to stop the thread by throwing a detail::abort_thread exception. If this exception is inadvertently caught, terminate() is called.

bool thread::active()

Returns true while the thread is live (not aborted or exited).

void thread::invoke(...)

Invokes the given function in this thread's context.

void thread::name(...)

Allows you to set a name for the thread, which will be displayed in gdb. This function is a no-op when compiled with NDEBUG.

Class jthread

The extensions for thread also apply to jthread.

Namespace this_thread

Contains the following functions to switch to other threads:

• yield
• yield_while
• yield_until
• yield_for
• yield_while_until
• yield_while_for

Additionally, alias functions sleep_...() are provided. These simply call the equivalent yield_...(). Use whichever you prefer.

Note that the interrupt flag is 'thread-local', that is, calling any yield function will re-enable interrupts if they were previously disabled.

void invoke_next(...)

Registers the given function to be called on the next active thread.

void invoke_main(...)

As above, but for the main thread.

Header <mutex>

Implemented in <jw/mutex.h>. Locking functionality (unique_lock, etc) is provided by libstc++.

The mutex classes in this header are based on atomic primitives, so they are suitable for use in interrupt context. The recursive mutexes also consider (potentially nested) interrupt contexts to be separate 'threads'.

Class once_flag, call_once()

Not implemented.

Header <shared_mutex>

Fully implemented in <jw/shared_mutex.h>.

Header <stop_token>

A complete implementation is provided by libstdc++, with no dependency on pthreads.

Header <future>

Fully implemented in <jw/future.h>. Some basic functionality (future_error, launch, etc) is provided by libstc++.

future<...> async(...)

Policy std::launch::deferred is not implemented.

Header <condition_variable>

Not (yet) implemented.

Header <semaphore>

Not (yet) implemented.

Header <latch>

Not (yet) implemented.

Header <barrier>

Not (yet) implemented.