dfx::Utils::Thread Class Reference

A managed execution wrapper that ensures a Runnable's full lifecycle occurs within the worker thread. More...

#include <dfx-utilities/Thread.hpp>

Public Member Functions
template<Runnable R, typename ... Args>
	Thread (std::in_place_type_t< R >, std::string threadName, Args &&... args)
	Constructs the Thread and enters the worker loop.
	DFX_ENABLE_DEFAULT_MOVE_DISABLE_COPY_NOEXCEPT (Thread)
void	waitForStarted ()
	Blocks until the worker thread has reached the start of the Runnable lifecycle.
void	stop (bool waitForFinished=false) noexcept
	Signals the worker thread to stop.
std::jthread const &	nativeThread () const noexcept
	Access the underlying jthread instance.
template<Runnable R>
R &	getRunnable () const
	Access the constructed Runnable.

Static Public Member Functions
template<Runnable R, typename ... Args>
static Thread	create (std::string threadName, Args &&... args)
	Factory method for creating a Thread.
static void	setName (std::string_view name, std::error_code &ec) noexcept
	Set the calling thread name.
static void	setName (std::string_view name)
	Set the calling thread name.
static std::string	getName (std::error_code &ec) noexcept
	Get the calling thread name.
static std::string	getName ()
	Get the calling thread name.

Detailed Description

A managed execution wrapper that ensures a Runnable's full lifecycle occurs within the worker thread.

Unlike standard threading utilities where an object might be constructed in the parent thread and used in a worker, this class ensures that the Runnable R is:

1. Constructed inside the new thread.
2. Executed inside the new thread.
3. Destroyed inside the new thread. This design prevents "affinity leakage," where members of a worker object might accidentally depend on the stack or thread-local state of the launcher thread.

Note

This class is move-only to maintain ownership of the underlying std::jthread.

Constructor & Destructor Documentation

Thread()

template<Runnable R, typename ... Args>

dfx::Utils::Thread::Thread ( std::in_place_type_t< R > , std::string threadName, Args &&... args )

inline

Constructs the Thread and enters the worker loop.

The internal lambda captures the constructor arguments and moves them into the new thread context before instantiating the Runnable R.

Template Parameters

R	The Runnable type to instantiate.
Args	Variadic arguments passed to R's constructor.

Parameters

threadName	The system-level name for the thread (max 15 chars).
args	Additional argument passed to the Runnable constructor.

See also

waitForStarted

Member Function Documentation

create()

template<Runnable R, typename ... Args>

Thread dfx::Utils::Thread::create ( std::string threadName, Args &&... args )

inlinestatic

Factory method for creating a Thread.

auto worker = Thread::create<MyTask>("MyWorker", 42, "config.json");

getName() [1/2]

std::string dfx::Utils::Thread::getName ( )

static

Get the calling thread name.

Returns

The current thread name.

Convenience overload of getName(std::error_code&). On failure, this overload reports the error by throwing

getName() [2/2]

std::string dfx::Utils::Thread::getName ( std::error_code & ec )

staticnoexcept

Get the calling thread name.

Parameters

ec	Output error code. Set to a non-zero value on failure; cleared on success.

Returns

The current thread name on success; an empty string on failure.

Retrieves the name of the current thread. On failure, the function does not throw and instead reports the error via ec.

getRunnable()

template<Runnable R>

R & dfx::Utils::Thread::getRunnable ( ) const

inline

Access the constructed Runnable.

Note that this function is very naive and doesn't perform any checks.

nativeThread()

std::jthread const & dfx::Utils::Thread::nativeThread ( ) const

inlinenoexcept

Access the underlying jthread instance.

setName() [1/2]

void dfx::Utils::Thread::setName ( std::string_view name )

static

Set the calling thread name.

Parameters

name	New thread name.

Convenience overload of setName(std::string_view,std::error_code&). On failure, this overload reports the error by throwing.

setName() [2/2]

void dfx::Utils::Thread::setName ( std::string_view name, std::error_code & ec )

staticnoexcept

Set the calling thread name.

Parameters

name	New thread name.
ec	Output error code. Set to a non-zero value on failure; cleared on success.

Sets the name of the current thread to name. On failure, the function does not throw and instead reports the error via ec.

stop()

void dfx::Utils::Thread::stop ( bool waitForFinished = false )

noexcept

Signals the worker thread to stop.

Parameters

waitForFinished

If true, the call blocks until the worker thread joins.

waitForStarted()

void dfx::Utils::Thread::waitForStarted ( )

inline

Blocks until the worker thread has reached the start of the Runnable lifecycle.

This ensures that the thread name is set and the internal promise is fulfilled before the caller continues.

After this function, getRunnable can be used.

---

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

• lib/dfx-utilities/Thread.hpp