Thread Class Reference

A platform thread. More...

#include <Thread.h>

Public Member Functions
	~Thread ()
	Joins the thread if it's still running, same as calling join().
	Thread (const Thread &)=delete
Thread &	operator= (const Thread &)=delete
bool	start (ThreadEntry entry, void *arg=nullptr, uint32_t stackSize=8192, ThreadPriority priority=ThreadPriority::Normal, void(*wake)(void)=nullptr)
	Starts entry(arg) running on a new thread.
void	join ()
	Blocks until the thread exits.
void	cancel ()
	Requests the thread stop at its next safe point without blocking.
void	suspend ()
	Suspends thread execution.
void	resume ()
	Resumes a suspended thread.
bool	isSuspended () const
bool	isRunning () const
void	requestStop ()
	Sets the flag entry() should check (via stopRequested()) to know it should return, and invokes the wake callback passed to start(), if any.
bool	stopRequested () const

Static Public Member Functions
static void	JoinAll ()
	Requests every currently-registered, still-running Thread stop (per its own wake callback, if any) and joins each in turn.

Protected Attributes
void *	handle = nullptr
	Backend-assigned thread handle.
volatile bool	stopFlag = false
	Set by requestStop(); polled by entry() via stopRequested()
void(*	wakeFn )(void) = nullptr
	Optional callback to break entry() out of a wait; set by start()
Thread *	registryNext = nullptr
	Intrusive next-pointer for the JoinAll() registry.

Detailed Description

A platform thread.

Owns at most one running/joinable backend thread at a time - start() on an already-running Thread fails rather than leaking the previous one.

Every Thread that successfully start()s registers itself in a process- wide list (removed again on join()) so that JoinAll() can be used as a single, generic app-exit safety net: it stops and joins every thread still outstanding, regardless of which subsystem started it or whether that subsystem remembered to tear it down itself. This does not replace a subsystem's own halt/resume pausing during normal operation - it's the final guarantee that nothing is left running (and touching platform/ driver state) once shutdown begins in earnest.

Definition at line 39 of file Thread.h.

Constructor & Destructor Documentation

Thread()

Thread::Thread ( )

inline

Definition at line 42 of file Thread.h.

~Thread()

Thread::~Thread

(

)

Joins the thread if it's still running, same as calling join().

Definition at line 14 of file Thread.cpp.

Member Function Documentation

cancel()

void Thread::cancel

(

)

Requests the thread stop at its next safe point without blocking.

This is a best-effort operation and may leak backend resources (see ThreadDriver::cancelThread) - prefer signalling the thread to exit and calling join() where the entry function can cooperate.

Definition at line 99 of file Thread.cpp.

isRunning()

bool Thread::isRunning ( ) const

inline

Returns

true if start() has an outstanding thread that hasn't been joined or cancelled yet

Definition at line 79 of file Thread.h.

isSuspended()

bool Thread::isSuspended

(

)

const

Returns

true if the thread is currently suspended

Definition at line 121 of file Thread.cpp.

join()

void Thread::join

(

)

Blocks until the thread exits.

Definition at line 46 of file Thread.cpp.

JoinAll()

void Thread::JoinAll ( )

static

Requests every currently-registered, still-running Thread stop (per its own wake callback, if any) and joins each in turn.

Intended to be called once, late in app shutdown - after this returns, no background thread started via Thread::start() can still be touching platform/driver state.

Examples

demo.cpp.

Definition at line 78 of file Thread.cpp.

requestStop()

void Thread::requestStop

(

)

Sets the flag entry() should check (via stopRequested()) to know it should return, and invokes the wake callback passed to start(), if any.

Does not block - call join() afterward to wait for entry() to actually return. Safe to call from any thread.

Definition at line 71 of file Thread.cpp.

resume()

void Thread::resume

(

)

Resumes a suspended thread.

Definition at line 115 of file Thread.cpp.

start()

bool Thread::start	(	ThreadEntry	entry,
		void *	arg = nullptr,
		uint32_t	stackSize = 8192,
		ThreadPriority	priority = ThreadPriority::Normal,
		void(*	wake )(void) = nullptr )

Starts entry(arg) running on a new thread.

Parameters

entry	Thread entry point
arg	Argument passed to entry
stackSize	Stack size in bytes for the new thread
priority	Backend-defined thread priority
wake	Optional callback JoinAll()/requestStop() invokes to break entry() out of whatever wait it may be parked in once a stop has been requested - eg. signalling the cond it sleeps on. Not needed if entry() only ever polls stopRequested() between short, bounded waits.

Returns

true on success, false if a thread is already running or the backend failed to create one

Definition at line 19 of file Thread.cpp.

stopRequested()

bool Thread::stopRequested ( ) const

inline

Returns

true once requestStop() has been called for this Thread. entry() should check this in its loop condition(s) instead of a private bool, so a generic caller (JoinAll()) can stop threads it didn't start and knows nothing else about.

Definition at line 90 of file Thread.h.

suspend()

void Thread::suspend

(

)

Suspends thread execution.

The thread itself keeps running once resumed - suspend is not a substitute for stopping it.

Definition at line 109 of file Thread.cpp.

Member Data Documentation

handle

void* Thread::handle = nullptr

protected

Backend-assigned thread handle.

Definition at line 100 of file Thread.h.

registryNext

Thread* Thread::registryNext = nullptr

protected

Intrusive next-pointer for the JoinAll() registry.

Definition at line 103 of file Thread.h.

stopFlag

volatile bool Thread::stopFlag = false

protected

Set by requestStop(); polled by entry() via stopRequested()

Definition at line 101 of file Thread.h.

wakeFn

void(* Thread::wakeFn) (void) = nullptr

protected

Optional callback to break entry() out of a wait; set by start()

Definition at line 102 of file Thread.h.

---

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

• source/drivers/Thread.h
• source/drivers/Thread.cpp