Multi-threaded background worker service owning a dedicated std::jthread. Integrates incoming event queue with background worker execution and cooperative shutdown via std::stop_token. Zero heap allocations, zero vtables/RTTI. More...

#include <BackgroundService.hpp>

Inheritance diagram for corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >:

Collaboration diagram for corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >:

Public Types
using	Base = Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >

using	EventVariant = typename Base::EventVariant

using	IncomingBus = BasicEventBus< EventVariant, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >

Public Member Functions
	BackgroundService ()=default

	BackgroundService (BackgroundService &&) noexcept=default

	BackgroundService (const BackgroundService &)=delete

	BackgroundService (ServiceContextT< EventVariant > context)

void	join () noexcept
	Join background std::jthread cleanly.

EventSinkT< EventVariant >	mainSink () const noexcept
	Get an EventSink handle targeting the main application event queue.

template<typename Handler >
bool	on (Handler &&handler)
	Register an event handler for incoming events with automatic event type deduction.

BackgroundService &	operator= (BackgroundService &&) noexcept=default

BackgroundService &	operator= (const BackgroundService &)=delete

bool	processOne ()
	Process a single incoming event from the service queue.

std::size_t	pump ()
	Pump all pending incoming events from the queue until empty.

std::size_t	pump (std::size_t maxEvents)
	Pump up to maxEvents pending incoming events from the queue.

template<typename EventType , typename Handler >
bool	registerHandler (Handler &&handler)
	Register an event handler for incoming events with explicit event type parameter.

void	setContext (ServiceContextT< EventVariant > context) noexcept

EventSinkT< EventVariant >	sink () noexcept
	Get an EventSink handle targeting this service's incoming event queue.

template<typename Derived >
void	startThread (Derived *derived)
	Start execution loop on dedicated std::jthread.

void	stop () noexcept
	Request cancellation on worker std::jthread.

template<typename Rep , typename Period >
std::size_t	waitAndPump (const std::stop_token &stopToken, const std::chrono::duration< Rep, Period > &timeout)
	Wait for incoming events or timeout, then pump all available incoming events. Safe for use inside worker thread run(std::stop_token).

	~BackgroundService ()

Protected Member Functions
const ServiceContextT< EventVariant > &	context () const noexcept

ServiceContextT< EventVariant > &	context () noexcept

const IncomingBus &	incomingBus () const noexcept

IncomingBus &	incomingBus () noexcept

template<typename EventType >
void	post (EventType &&event, EventPriority priority=EventPriority::Normal) const
	Post an event into the main application event queue.

template<typename EventType >
void	postHighPriority (EventType &&event) const
	Post a high-priority event into the main application event queue.

template<typename TargetService , typename EventType >
bool	sendToService (EventType &&event, EventPriority priority=EventPriority::Normal) const
	Post an event directly to another registered service.

Detailed Description

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>
class corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >

Multi-threaded background worker service owning a dedicated std::jthread. Integrates incoming event queue with background worker execution and cooperative shutdown via std::stop_token. Zero heap allocations, zero vtables/RTTI.

Template Parameters

EventVariantType	Supported event variant type list.
QueuePolicy	Strategy for queueing incoming events (bounded lock-free MPSC).
SignalPolicy	Strategy for signaling (CallbackSignalPolicy default).
StoragePolicy	Strategy for compile-time handler capacity and delegate storage.
OverflowPolicy	Strategy for queue overflow handling.

Member Typedef Documentation

◆ Base

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

using corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::Base = Service<EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy>

◆ EventVariant

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

using corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::EventVariant = typename Base::EventVariant

◆ IncomingBus

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

using corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::IncomingBus = BasicEventBus<EventVariant, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy>

inherited

Constructor & Destructor Documentation

◆ BackgroundService() [1/4]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::BackgroundService ( )

default

◆ BackgroundService() [2/4]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::BackgroundService ( ServiceContextT< EventVariant > context )

inlineexplicit

◆ ~BackgroundService()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::~BackgroundService ( )

inline

Here is the call graph for this function:

◆ BackgroundService() [3/4]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::BackgroundService ( const BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy > & )

delete

◆ BackgroundService() [4/4]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::BackgroundService ( BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy > && )

defaultnoexcept

Member Function Documentation

◆ context() [1/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

const ServiceContextT< EventVariant > & corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::context ( ) const

inlineprotectednoexceptinherited

◆ context() [2/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

ServiceContextT< EventVariant > & corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::context ( )

inlineprotectednoexceptinherited

Here is the caller graph for this function:

◆ incomingBus() [1/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

const IncomingBus & corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::incomingBus ( ) const

inlineprotectednoexceptinherited

◆ incomingBus() [2/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

IncomingBus & corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::incomingBus ( )

inlineprotectednoexceptinherited

Here is the caller graph for this function:

◆ join()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

void corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::join ( )

inlinenoexcept

Join background std::jthread cleanly.

Here is the caller graph for this function:

◆ mainSink()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

EventSinkT< EventVariant > corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::mainSink ( ) const

inlinenoexceptinherited

Get an EventSink handle targeting the main application event queue.

Here is the caller graph for this function:

◆ on()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

template<typename Handler >

bool corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::on ( Handler && handler )

inlineinherited

Register an event handler for incoming events with automatic event type deduction.

Here is the call graph for this function:

◆ operator=() [1/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

BackgroundService & corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::operator= ( BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy > && )

defaultnoexcept

◆ operator=() [2/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

BackgroundService & corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::operator= ( const BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy > & )

delete

◆ post()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

template<typename EventType >

void corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::post	(	EventType &&	event,
		EventPriority	priority = `EventPriority::Normal`
	)		const

inlineprotectedinherited

Post an event into the main application event queue.

◆ postHighPriority()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

template<typename EventType >

void corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::postHighPriority ( EventType && event ) const

inlineprotectedinherited

Post a high-priority event into the main application event queue.

Here is the caller graph for this function:

◆ processOne()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

bool corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::processOne ( )

inlineinherited

Process a single incoming event from the service queue.

Returns: true if an event was popped and dispatched; false if queue was empty.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ pump() [1/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

std::size_t corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::pump ( )

inlineinherited

Pump all pending incoming events from the queue until empty.

Returns: Number of events processed.

Here is the call graph for this function:

◆ pump() [2/2]

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

std::size_t corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::pump ( std::size_t maxEvents )

inlineinherited

Pump up to maxEvents pending incoming events from the queue.

Parameters

maxEvents Maximum number of events to process.

Returns: Number of events processed.

Here is the call graph for this function:

◆ registerHandler()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

template<typename EventType , typename Handler >

bool corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::registerHandler ( Handler && handler )

inlineinherited

Register an event handler for incoming events with explicit event type parameter.

◆ sendToService()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

template<typename TargetService , typename EventType >

bool corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::sendToService	(	EventType &&	event,
		EventPriority	priority = `EventPriority::Normal`
	)		const

inlineprotectedinherited

Post an event directly to another registered service.

◆ setContext()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

void corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::setContext ( ServiceContextT< EventVariant > context )

inlinenoexceptinherited

Here is the call graph for this function:

◆ sink()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

EventSinkT< EventVariant > corium::Service< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::sink ( )

inlinenoexceptinherited

Get an EventSink handle targeting this service's incoming event queue.

Here is the call graph for this function:

◆ startThread()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

template<typename Derived >

void corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::startThread ( Derived * derived )

inline

Start execution loop on dedicated std::jthread.

Here is the call graph for this function:

◆ stop()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

void corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::stop ( )

inlinenoexcept

Request cancellation on worker std::jthread.

Here is the caller graph for this function:

◆ waitAndPump()

template<typename EventVariantType = DefaultEvents, typename QueuePolicy = BoundedMpscQueuePolicy<EventVariantType, 1024>, typename SignalPolicy = CallbackSignalPolicy, typename StoragePolicy = DefaultStoragePolicy, typename OverflowPolicy = DropNewestOverflowPolicy>

template<typename Rep , typename Period >

std::size_t corium::BackgroundService< EventVariantType, QueuePolicy, SignalPolicy, StoragePolicy, OverflowPolicy >::waitAndPump	(	const std::stop_token &	stopToken,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Wait for incoming events or timeout, then pump all available incoming events. Safe for use inside worker thread run(std::stop_token).

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

stopToken	std::stop_token from run(stopToken).
timeout	Maximum duration to wait if queue is empty.

Returns: Number of events processed.

Here is the call graph for this function:

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

include/corium/BackgroundService.hpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ Base

◆ EventVariant

◆ IncomingBus

Constructor & Destructor Documentation

◆ BackgroundService() [1/4]

◆ BackgroundService() [2/4]

◆ ~BackgroundService()

◆ BackgroundService() [3/4]

◆ BackgroundService() [4/4]

Member Function Documentation

◆ context() [1/2]

◆ context() [2/2]

◆ incomingBus() [1/2]

◆ incomingBus() [2/2]

◆ join()

◆ mainSink()

◆ on()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ post()

◆ postHighPriority()

◆ processOne()

◆ pump() [1/2]

◆ pump() [2/2]

◆ registerHandler()

◆ sendToService()

◆ setContext()

◆ sink()

◆ startThread()

◆ stop()

◆ waitAndPump()