kcenon::thread::lifecycle_controller Class Reference

Centralized thread lifecycle state and synchronization management. More...

#include <lifecycle_controller.h>

Collaboration diagram for kcenon::thread::lifecycle_controller:

Public Member Functions
	lifecycle_controller (const lifecycle_controller &)=delete
lifecycle_controller &	operator= (const lifecycle_controller &)=delete
	lifecycle_controller (lifecycle_controller &&)=delete
lifecycle_controller &	operator= (lifecycle_controller &&)=delete
	lifecycle_controller ()
	Constructs a new lifecycle_controller in Created state.
	~lifecycle_controller ()=default
	Destructor.
auto	get_state () const noexcept -> thread_conditions
	Gets the current thread condition/state.
auto	set_state (thread_conditions state) noexcept -> void
	Sets the thread condition/state.
auto	is_running () const noexcept -> bool
	Checks if the thread is currently running.
auto	set_stopped () noexcept -> void
	Marks the thread as stopped.
auto	initialize_for_start () -> void
	Initializes the controller for a new thread start.
auto	request_stop () noexcept -> void
	Requests the thread to stop.
auto	is_stop_requested () const noexcept -> bool
	Checks if a stop has been requested.
auto	has_active_source () const noexcept -> bool
	Checks if the controller has an active stop source (C++20 only).
auto	reset_stop_source () noexcept -> void
	Resets the stop control mechanism after thread completion.
auto	acquire_lock () -> std::unique_lock< std::mutex >
	Acquires a unique lock on the condition variable mutex.
template<typename Predicate >
auto	wait (std::unique_lock< std::mutex > &lock, Predicate pred) -> void
	Waits on the condition variable with a predicate.
template<typename Rep , typename Period , typename Predicate >
auto	wait_for (std::unique_lock< std::mutex > &lock, const std::chrono::duration< Rep, Period > &timeout, Predicate pred) -> bool
	Waits on the condition variable with a timeout and predicate.
auto	notify_one () -> void
	Notifies one waiting thread.
auto	notify_all () -> void
	Notifies all waiting threads.

Private Attributes
std::mutex	cv_mutex_
	Mutex for condition variable operations.
std::condition_variable	condition_
	Condition variable for thread signaling.
std::atomic< thread_conditions >	state_ {thread_conditions::Created}
	Current thread state.
std::atomic< bool >	stop_requested_ {false}
	Atomic flag for stop request (legacy mode).

Detailed Description

Centralized thread lifecycle state and synchronization management.

The lifecycle_controller class consolidates duplicated thread lifecycle management patterns (start, stop, state transitions, condition variables) into a single reusable component. Thread classes can use composition with this controller instead of implementing these patterns themselves.

Key Features

• Thread state management (Created, Waiting, Working, Stopping, Stopped)
• Condition variable signaling for wake-ups
• Stop request handling (supports both std::jthread and legacy std::thread)
• Thread-safe state queries and transitions

Thread Safety

All public methods are thread-safe. The class uses internal synchronization to protect state transitions and condition variable operations.

Example Usage

class my_thread {
private:
    lifecycle_controller lifecycle_;
 
public:
    void start() {
        lifecycle_.initialize_for_start();
        // spawn thread...
    }
 
    void stop() {
        lifecycle_.request_stop();
        lifecycle_.notify_all();
        // join thread...
        lifecycle_.set_stopped();
    }
 
    void worker_loop() {
        while (!lifecycle_.is_stop_requested() || has_work()) {
            lifecycle_.set_state(thread_conditions::Waiting);
            lifecycle_.wait_for(timeout, [this] { return has_work(); });
            lifecycle_.set_state(thread_conditions::Working);
            do_work();
        }
    }
};

Definition at line 79 of file lifecycle_controller.h.

Constructor & Destructor Documentation

lifecycle_controller() [1/3]

kcenon::thread::lifecycle_controller::lifecycle_controller ( const lifecycle_controller & )

delete

lifecycle_controller() [2/3]

kcenon::thread::lifecycle_controller::lifecycle_controller ( lifecycle_controller && )

delete

lifecycle_controller() [3/3]

kcenon::thread::lifecycle_controller::lifecycle_controller

(

)

Constructs a new lifecycle_controller in Created state.

Definition at line 9 of file lifecycle_controller.cpp.

        : state_(thread_conditions::Created)
#ifdef USE_STD_JTHREAD
        , stop_source_(std::nullopt)
#else
        , stop_requested_(false)
#endif
    {
    }

~lifecycle_controller()

kcenon::thread::lifecycle_controller::~lifecycle_controller ( )

default

Destructor.

Member Function Documentation

acquire_lock()

auto kcenon::thread::lifecycle_controller::acquire_lock ( ) -> std::unique_lock<std::mutex>

nodiscard

Acquires a unique lock on the condition variable mutex.

Returns

A unique_lock holding the mutex.

Use this to prepare for wait operations.

Definition at line 95 of file lifecycle_controller.cpp.

    {
        return std::unique_lock<std::mutex>(cv_mutex_);
    }

get_state()

auto kcenon::thread::lifecycle_controller::get_state ( ) const -> thread_conditions

nodiscardnoexcept

Gets the current thread condition/state.

Returns

The current thread_conditions value.

Thread Safety:

• Safe to call from any thread
• Uses atomic load with acquire memory ordering

Definition at line 19 of file lifecycle_controller.cpp.

    {
        return state_.load(std::memory_order_acquire);
    }

References state_.

has_active_source()

auto kcenon::thread::lifecycle_controller::has_active_source ( ) const -> bool

nodiscardnoexcept

Checks if the controller has an active stop source (C++20 only).

Returns

true if a stop_source is active, false otherwise.

In legacy mode, checks if stop has NOT been requested (indicating active state).

Definition at line 76 of file lifecycle_controller.cpp.

    {
#ifdef USE_STD_JTHREAD
        return stop_source_.has_value();
#else
        // In legacy mode, check if we're in an active state (not stopped/created)
        auto state = state_.load(std::memory_order_acquire);
        return state == thread_conditions::Working ||
               state == thread_conditions::Waiting;
#endif
    }

References state_, kcenon::thread::Waiting, and kcenon::thread::Working.

initialize_for_start()

auto kcenon::thread::lifecycle_controller::initialize_for_start

(

)

-> void

Initializes the controller for a new thread start.

Resets the stop request flag and prepares for a new thread lifecycle. In C++20 jthread mode, creates a new stop_source.

Note

Must be called before spawning the worker thread.

Definition at line 41 of file lifecycle_controller.cpp.

    {
#ifdef USE_STD_JTHREAD
        stop_source_ = std::stop_source();
#else
        stop_requested_.store(false, std::memory_order_release);
#endif
        set_state(thread_conditions::Created);
    }

References kcenon::thread::Created.

is_running()

auto kcenon::thread::lifecycle_controller::is_running ( ) const -> bool

nodiscardnoexcept

Checks if the thread is currently running.

Returns

true if state is Working or Waiting, false otherwise.

Definition at line 29 of file lifecycle_controller.cpp.

    {
        auto condition = state_.load(std::memory_order_acquire);
        return condition == thread_conditions::Working ||
               condition == thread_conditions::Waiting;
    }

References state_, kcenon::thread::Waiting, and kcenon::thread::Working.

is_stop_requested()

auto kcenon::thread::lifecycle_controller::is_stop_requested ( ) const -> bool

nodiscardnoexcept

Checks if a stop has been requested.

Returns

true if stop has been requested, false otherwise.

Thread Safety:

• Safe to call from any thread

Definition at line 63 of file lifecycle_controller.cpp.

    {
#ifdef USE_STD_JTHREAD
        if (stop_source_.has_value())
        {
            return stop_source_.value().stop_requested();
        }
        return true;
#else
        return stop_requested_.load(std::memory_order_acquire);
#endif
    }

References stop_requested_.

notify_all()

auto kcenon::thread::lifecycle_controller::notify_all

(

)

-> void

Notifies all waiting threads.

Thread Safety:

• Safe to call from any thread

Definition at line 106 of file lifecycle_controller.cpp.

    {
        std::scoped_lock<std::mutex> lock(cv_mutex_);
        condition_.notify_all();
    }

notify_one()

auto kcenon::thread::lifecycle_controller::notify_one

(

)

-> void

Notifies one waiting thread.

Thread Safety:

• Safe to call from any thread

Definition at line 100 of file lifecycle_controller.cpp.

    {
        std::scoped_lock<std::mutex> lock(cv_mutex_);
        condition_.notify_one();
    }

operator=() [1/2]

lifecycle_controller & kcenon::thread::lifecycle_controller::operator= ( const lifecycle_controller & )

delete

operator=() [2/2]

lifecycle_controller & kcenon::thread::lifecycle_controller::operator= ( lifecycle_controller && )

delete

request_stop()

auto kcenon::thread::lifecycle_controller::request_stop ( ) -> void

noexcept

Requests the thread to stop.

In C++20 mode, calls request_stop() on the stop_source. In legacy mode, sets the atomic stop_requested_ flag to true.

Thread Safety:

• Safe to call from any thread
• The request is visible to the worker thread immediately

Definition at line 51 of file lifecycle_controller.cpp.

    {
#ifdef USE_STD_JTHREAD
        if (stop_source_.has_value())
        {
            stop_source_.value().request_stop();
        }
#else
        stop_requested_.store(true, std::memory_order_release);
#endif
    }

References stop_requested_.

reset_stop_source()

auto kcenon::thread::lifecycle_controller::reset_stop_source ( ) -> void

noexcept

Resets the stop control mechanism after thread completion.

In C++20 mode, resets the stop_source. Should be called after thread join to clean up resources.

Definition at line 88 of file lifecycle_controller.cpp.

    {
#ifdef USE_STD_JTHREAD
        stop_source_.reset();
#endif
    }

set_state()

auto kcenon::thread::lifecycle_controller::set_state ( thread_conditions state ) -> void

noexcept

Sets the thread condition/state.

Parameters

state

The new thread_conditions value.

Thread Safety:

• Safe to call from any thread
• Uses atomic store with release memory ordering

Definition at line 24 of file lifecycle_controller.cpp.

    {
        state_.store(state, std::memory_order_release);
    }

Referenced by set_stopped().

Here is the caller graph for this function:

set_stopped()

auto kcenon::thread::lifecycle_controller::set_stopped ( ) -> void

noexcept

Marks the thread as stopped.

Convenience method equivalent to set_state(thread_conditions::Stopped).

Definition at line 36 of file lifecycle_controller.cpp.

    {
        set_state(thread_conditions::Stopped);
    }

References set_state(), and kcenon::thread::Stopped.

Here is the call graph for this function:

wait()

template<typename Predicate >

auto kcenon::thread::lifecycle_controller::wait ( std::unique_lock< std::mutex > & lock, Predicate pred ) -> void

inline

Waits on the condition variable with a predicate.

Template Parameters

Predicate

A callable returning bool.

Parameters

lock	The unique_lock (must be holding cv_mutex_).
pred	The predicate to check.

Waits until pred() returns true OR stop is requested.

Definition at line 206 of file lifecycle_controller.h.

        {
#ifdef USE_STD_JTHREAD
            if (stop_source_.has_value())
            {
                auto stop_token = stop_source_.value().get_token();
                condition_.wait(lock, [this, &stop_token, &pred]() {
                    return stop_token.stop_requested() || pred();
                });
            }
            else
            {
                condition_.wait(lock, pred);
            }
#else
            condition_.wait(lock, [this, &pred]() {
                return stop_requested_.load(std::memory_order_acquire) || pred();
            });
#endif
        }

wait_for()

template<typename Rep , typename Period , typename Predicate >

auto kcenon::thread::lifecycle_controller::wait_for ( std::unique_lock< std::mutex > & lock, const std::chrono::duration< Rep, Period > & timeout, Predicate pred ) -> bool

inline

Waits on the condition variable with a timeout and predicate.

Template Parameters

Rep	Duration rep type.
Period	Duration period type.
Predicate	A callable returning bool.

Parameters

lock	The unique_lock (must be holding cv_mutex_).
timeout	The maximum duration to wait.
pred	The predicate to check.

Returns

true if pred() is satisfied, false if timed out.

Definition at line 238 of file lifecycle_controller.h.

        {
#ifdef USE_STD_JTHREAD
            if (stop_source_.has_value())
            {
                auto stop_token = stop_source_.value().get_token();
                return condition_.wait_for(lock, timeout, [this, &stop_token, &pred]() {
                    return stop_token.stop_requested() || pred();
                });
            }
            else
            {
                return condition_.wait_for(lock, timeout, pred);
            }
#else
            return condition_.wait_for(lock, timeout, [this, &pred]() {
                return stop_requested_.load(std::memory_order_acquire) || pred();
            });
#endif
        }

Member Data Documentation

condition_

std::condition_variable kcenon::thread::lifecycle_controller::condition_

private

Condition variable for thread signaling.

Definition at line 282 of file lifecycle_controller.h.

cv_mutex_

std::mutex kcenon::thread::lifecycle_controller::cv_mutex_

private

Mutex for condition variable operations.

Definition at line 279 of file lifecycle_controller.h.

state_

std::atomic<thread_conditions> kcenon::thread::lifecycle_controller::state_ {thread_conditions::Created}

private

Current thread state.

Definition at line 285 of file lifecycle_controller.h.

{thread_conditions::Created};

Referenced by get_state(), has_active_source(), and is_running().

stop_requested_

std::atomic<bool> kcenon::thread::lifecycle_controller::stop_requested_ {false}

private

Atomic flag for stop request (legacy mode).

Definition at line 292 of file lifecycle_controller.h.

{false};

Referenced by is_stop_requested(), and request_stop().

---

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

• include/kcenon/thread/core/lifecycle_controller.h
• src/core/lifecycle_controller.cpp