qb::CoreInitializer Class Reference

Handles pre-start configuration for a single VirtualCore. More...

#include <Main.h>

Inheritance diagram for qb::CoreInitializer:

Collaboration diagram for qb::CoreInitializer:

Classes
class	ActorBuilder
	Helper to fluently build multiple Actors for a CoreInitializer. More...

Public Member Functions
	CoreInitializer (CoreId index)
	Constructor for CoreInitializer.
	~CoreInitializer () noexcept
	Destructor.
void	clear () noexcept
	Clears all registered actor factories for this initializer.
template<typename _Actor, typename... _Args>
ActorId	addActor (_Args &&...args) noexcept
	Create and add a new _Actor to this VirtualCore.
ActorBuilder	builder () noexcept
	Get an ActorBuilder for this CoreInitializer.
CoreInitializer &	setAffinity (CoreIdSet const &cores={}) noexcept
	Set the CPU affinity for the VirtualCore associated with this initializer.
CoreInitializer &	setLatency (uint64_t latency=0) noexcept
	Set the maximum event loop latency for the VirtualCore.
CoreId	getIndex () const noexcept
	Gets the CoreId associated with this initializer.
CoreIdSet const &	getAffinity () const noexcept
	Gets the currently configured CPU affinity set for this core.
uint64_t	getLatency () const noexcept
	Gets the currently configured maximum event loop latency (in ns) for this core.

Detailed Description

Handles pre-start configuration for a single VirtualCore.

This class allows setting up properties like core affinity, event loop latency, and adding initial actors to a VirtualCore before the main engine starts. Instances are typically obtained via Main::core(core_id).

Constructor & Destructor Documentation

CoreInitializer()

qb::CoreInitializer::CoreInitializer ( CoreId index )

explicit

Constructor for CoreInitializer.

Parameters

index

The CoreId this initializer is for.

~CoreInitializer()

qb::CoreInitializer::~CoreInitializer ( )

noexcept

Destructor.

Cleans up actor factories.

Member Function Documentation

clear()

void qb::CoreInitializer::clear ( )

noexcept

Clears all registered actor factories for this initializer.

This removes any pending actor creation tasks that were added via addActor() or builder() but before the engine was started. Useful if re-configuration is needed before Main::start().

addActor()

template<typename _Actor, typename... _Args>

ActorId qb::CoreInitializer::addActor ( _Args &&... args )

noexcept

Create and add a new _Actor to this VirtualCore.

Template Parameters

_Actor	DerivedActor type to create.
_Args	Arguments to forward to the constructor of the _Actor.

Parameters

args	Arguments to forward to the _Actor's constructor.

Returns

ActorId of the created _Actor. Returns ActorId::NotFound on failure (e.g., duplicate ServiceActor, max actors reached).

Creates a new _Actor instance scheduled to run on the VirtualCore associated with this CoreInitializer. Example:

// auto id = main.core(0).addActor<MyActor>(param1, param2);
// if (id.is_valid()) { ... }

Attention

This function is only available before the engine is running.

builder()

ActorBuilder qb::CoreInitializer::builder ( )

nodiscardnoexcept

Get an ActorBuilder for this CoreInitializer.

Returns

An ActorBuilder instance for fluently adding multiple actors to this core.

Attention

Each call to builder() returns a new ActorBuilder instance.

// auto builder1 = main.core(0).builder();
// auto builder2 = main.core(0).builder();
// // Even though both builders configure the same VirtualCore,
// // builder1 and builder2 are distinct objects.

setAffinity()

CoreInitializer & qb::CoreInitializer::setAffinity ( CoreIdSet const & cores = {} )

noexcept

Set the CPU affinity for the VirtualCore associated with this initializer.

Parameters

cores

A CoreIdSet specifying the set of physical CPU cores this VirtualCore thread should be allowed to run on. An empty set typically means default OS scheduling.

Returns

Reference to this CoreInitializer for method chaining.

Note

By default, affinity is typically set to allow the VirtualCore thread to run on any CPU. This setting takes effect when the engine starts.

setLatency()

CoreInitializer & qb::CoreInitializer::setLatency ( uint64_t latency = 0 )

noexcept

Set the maximum event loop latency for the VirtualCore.

Parameters

latency

The maximum time in nanoseconds the VirtualCore's event loop will wait if it hasn't received any core/IO events. Defaults to 0.

Returns

Reference to this CoreInitializer for method chaining.

Note

• 0 (default): Low latency mode. The VirtualCore spins actively, consuming 100% CPU on its assigned core, to process events with minimal delay.
• latency > 0: The VirtualCore may sleep for up to this duration if idle, reducing CPU usage. This introduces a potential worst-case latency for new event processing. This setting takes effect when the engine starts.

getIndex()

CoreId qb::CoreInitializer::getIndex ( ) const

nodiscardnoexcept

Gets the CoreId associated with this initializer.

Returns

The CoreId (unsigned short) of the VirtualCore this initializer configures.

getAffinity()

CoreIdSet const & qb::CoreInitializer::getAffinity ( ) const

nodiscardnoexcept

Gets the currently configured CPU affinity set for this core.

Returns

Const reference to a CoreIdSet representing the CPU cores this VirtualCore may run on.

getLatency()

uint64_t qb::CoreInitializer::getLatency ( ) const

nodiscardnoexcept

Gets the currently configured maximum event loop latency (in ns) for this core.

Returns

uint64_t latency value in nanoseconds. See setLatency() for interpretation.