chronon::TickSimulation

More...

#include <TickSimulation.hpp>

Public Functions

	Name
	~TickSimulation()
void	writeTimelineTrace() Write the scheduler execution timeline at end of run.
bool	wasTerminationRequested() const
bool	usesClockDomains() const
bool	useParallelExecution() const
size_t	unitCount() const
size_t	transparentBroadcastConnectionCount() const
uint64_t	totalTransportOverflowEvents() const
uint64_t	totalStagingOverflowEvents() const
const std::string &	timelineTraceFile() const
bool	timelineTraceEnabled() const
uint64_t	tickFrequencyHz() const
const TerminationRequest &	terminationRequest() const Only valid after runUntilTermination() returns.
void	setUnitName(Unit & unit, std::string name) Assign the factory instance identity before initialization. Host-only.
void	setPrecomputedUnitCosts(std::vector< double > unit_costs, PlatformMetrics metrics) Provide explicit per-unit costs instead of using uniform-cost initial partitioning.
uint64_t	schedulerSteps() const
uint64_t	runUntilTime(SimTime exclusive_limit)
uint64_t	runUntilTermination(uint64_t max_cycles =UINT64_MAX)
uint64_t	runUntilComplete(uint64_t max_cycles =UINT64_MAX)
template <typename Predicate > uint64_t	runUntil(Predicate && should_stop, uint64_t max_cycles =UINT64_MAX) Run until should_stop() returns true or max_cycles reached.
uint64_t	runDomainCycles(ClockDomainId id, uint64_t additional_edges)
uint64_t	runClockEvents(uint64_t max_event_batches)
uint64_t	run(uint64_t num_cycles)
void	resetTermination() Reconstructs the stop_source (inplace_stop_source is non-resettable).
void	requestTermination(TerminationReason reason, int32_t exit_code =0, std::string_view message ="") Externally-driven termination, e.g. signal handlers or API calls.
void	registerConnection(ConnectionBase * connection) Type-erased connection registration used by configuration builders.
uint64_t	rebalanceCount() const
PortDirectory &	portDirectory()
const PortDirectory &	portDirectory() const
exec::static_thread_pool &	pool() Used by observation async I/O.
const std::string &	parallelFallbackReason() const
TickSimulation &	operator=(const TickSimulation & ) =delete
size_t	normalizeThreadCount(size_t requested)
SimTime	lastCommittedTime() const
bool	isParallelBeneficial() const
bool	isInitialized() const
bool	isFinalized() const
void	initialize()
bool	hasTightConnectionsInGraph() const
stdexec::inplace_stop_token	get_stop_token() const
const std::vector< double > &	getUnitCosts() const
TickableUnit *	getUnit(const std::string & name)
template <typename UnitT > UnitT *	getUnit(const std::string & name)
const PlatformMetrics &	getPlatformMetrics() const
void	forceStableConnectionQueues()
void	finalize()
uint64_t	epochFreeRunCount() const
uint64_t	drainCdc(uint64_t max_event_batches) Call after stopping producers; includes RAM, output registers and pointer synchronization.
uint64_t	domainCycleCount(ClockDomainId id) const
const DependencyGraph &	dependencyGraph() const
uint64_t	currentCycle() const
template <typename UnitT ,typename ParameterSetT > UnitT *	createUnitWithParameters(std::unique_ptr< ParameterSetT > parameters)
template <typename UnitT ,typename... Args> UnitT *	createUnitInDomain(ClockDomainId id, Args &&... args)
template <typename UnitT ,typename... Args> UnitT *	createUnit(Args &&... args)
template <typename T > AsyncFifo< T > *	connectAsyncFifo(uint32_t id, AsyncWritePort< T > & write, AsyncReadPort< T > & read, AsyncFifoConfig config ={})
template <typename T > Connection< T > *	connect(OutPort< T > & from, InPort< T > & to, uint32_t delay =1)
void	configureObservation(const observe::ObservationYAMLConfig & config)
void	configureClockTrace(observe::ClockTraceRecorder::Config config)
void	closeClockTrace()
observe::ClockTraceRecorder *	clockTraceRecorder()
const std::vector< ClockSchedulerProfile > &	clockSchedulerProfile() const Host-only, between run calls. Empty unless profile_clock_scheduler is enabled.
uint64_t	clockPartitionTimeNs() const
const ClockDomain &	clockDomain(ClockDomainId id) const
bool	cdcDrained() const
void	bindTreeNode(Unit & unit, tree::TreeNode & node)
size_t	assignedThread(Unit * unit) const
void	assignClockDomain(Unit & unit, ClockDomainId id)
const ClockDomain &	addClockDomain(ClockDomain domain) Static configuration only. ID 0 is the legacy default clock; UINT32_MAX is reserved.
	TickSimulation(const TickSimulationConfig & config ={})
	TickSimulation(const TickSimulation & ) =delete

Friends

	Name
struct	TransparentBroadcastFusionTestAccess Test-only transparent-broadcast fusion selection inspection.
struct	TransitiveDependencyPruneTestAccess Test-only white-box access for transitive dependency pruning.
struct	SchedulerScratchTestAccess
struct	PredecessorCycleCacheTestAccess Test-only white-box access for test_predecessor_cycle_cache.
struct	LookaheadFloorTestAccess Test-only white-box access for test_lookahead_floor_progress.
struct	EpochFreeDifferentialTestAccess
struct	DynamicMigrationTestAccess Test-only source-owner migration commit validation.
struct	ClockScalingTestAccess

Detailed Description

class chronon::TickSimulation;

High-performance simulation using stdexec.

Execution model: Chronon selects sequential or epoch-free lookahead at initialization. Tight clusters advance on dependency-progress atomics when the epoch-free safety gate proves that no barrier or per-epoch flush is required; otherwise the simulation uses the sequential reference path.

TickSimulation sim;
auto* fetch = sim.createUnit<FetchUnit>();
auto* decode = sim.createUnit<DecodeUnit>();
sim.connect(fetch->out, decode->in, 1);
sim.initialize();
sim.run(1'000'000);

Public Functions Documentation

function ~TickSimulation

~TickSimulation()

function writeTimelineTrace

void writeTimelineTrace()

Write the scheduler execution timeline at end of run.

Always written as a standalone file (scheduler_timeline.pftrace) separate from the simulation's timeline.pftrace. When the observation backend is running, the file is placed in its timestamped output directory; otherwise it is written relative to cwd.

function wasTerminationRequested

inline bool wasTerminationRequested() const

function usesClockDomains

inline bool usesClockDomains() const

function useParallelExecution

inline bool useParallelExecution() const

function unitCount

inline size_t unitCount() const

function transparentBroadcastConnectionCount

inline size_t transparentBroadcastConnectionCount() const

function totalTransportOverflowEvents

inline uint64_t totalTransportOverflowEvents() const

Total direct-lane pushes rejected by a full physical ring. Nonzero means the lookahead window outran transport capacity — a correctness failure. Always 0 for sequential execution.

function totalStagingOverflowEvents

inline uint64_t totalStagingOverflowEvents() const

function timelineTraceFile

inline const std::string & timelineTraceFile() const

function timelineTraceEnabled

inline bool timelineTraceEnabled() const

function tickFrequencyHz

inline uint64_t tickFrequencyHz() const

function terminationRequest

inline const TerminationRequest & terminationRequest() const

Only valid after runUntilTermination() returns.

function setUnitName

void setUnitName(
    Unit & unit,
    std::string name
)

Assign the factory instance identity before initialization. Host-only.

function setPrecomputedUnitCosts

inline void setPrecomputedUnitCosts(
    std::vector< double > unit_costs,
    PlatformMetrics metrics
)

Provide explicit per-unit costs instead of using uniform-cost initial partitioning.

function schedulerSteps

inline uint64_t schedulerSteps() const

function runUntilTime

uint64_t runUntilTime(
    SimTime exclusive_limit
)

function runUntilTermination

uint64_t runUntilTermination(
    uint64_t max_cycles =UINT64_MAX
)

Run until termination is requested or max_cycles is reached.

Termination is observed at scheduler boundaries with very low overhead; parallel lookahead paths also propagate the stop token into spin waits. If max_cycles is reached without a request, the controller is updated with MaxCyclesReached.

function runUntilComplete

inline uint64_t runUntilComplete(
    uint64_t max_cycles =UINT64_MAX
)

function runUntil

template <typename Predicate >
inline uint64_t runUntil(
    Predicate && should_stop,
    uint64_t max_cycles =UINT64_MAX
)

Run until should_stop() returns true or max_cycles reached.

function runDomainCycles

uint64_t runDomainCycles(
    ClockDomainId id,
    uint64_t additional_edges
)

function runClockEvents

uint64_t runClockEvents(
    uint64_t max_event_batches
)

Multiclock limits are explicit: event batches, absolute exclusive time, or a number of additional edges of one specified hardware domain. Parallel termination settles through the latest already-started edge; lastCommittedTime() can therefore exceed the termination request time.

function run

uint64_t run(
    uint64_t num_cycles
)

function resetTermination

inline void resetTermination()

Reconstructs the stop_source (inplace_stop_source is non-resettable).

function requestTermination

inline void requestTermination(
    TerminationReason reason,
    int32_t exit_code =0,
    std::string_view message =""
)

Externally-driven termination, e.g. signal handlers or API calls.

function registerConnection

void registerConnection(
    ConnectionBase * connection
)

Type-erased connection registration used by configuration builders.

function rebalanceCount

inline uint64_t rebalanceCount() const

function portDirectory

PortDirectory & portDirectory()

function portDirectory

const PortDirectory & portDirectory() const

function pool

inline exec::static_thread_pool & pool()

Used by observation async I/O.

function parallelFallbackReason

inline const std::string & parallelFallbackReason() const

function operator=

TickSimulation & operator=(
    const TickSimulation & 
) =delete

function normalizeThreadCount

static inline size_t normalizeThreadCount(
    size_t requested
)

function lastCommittedTime

inline SimTime lastCommittedTime() const

function isParallelBeneficial

inline bool isParallelBeneficial() const

function isInitialized

inline bool isInitialized() const

function isFinalized

inline bool isFinalized() const

function initialize

void initialize()

function hasTightConnectionsInGraph

inline bool hasTightConnectionsInGraph() const

function get_stop_token

inline stdexec::inplace_stop_token get_stop_token() const

Token reflects both unit-initiated termination and exception-driven abort. Used by external coordination (e.g. observation backends).

function getUnitCosts

inline const std::vector< double > & getUnitCosts() const

function getUnit

TickableUnit * getUnit(
    const std::string & name
)

function getUnit

template <typename UnitT >
inline UnitT * getUnit(
    const std::string & name
)

function getPlatformMetrics

inline const PlatformMetrics & getPlatformMetrics() const

function forceStableConnectionQueues

inline void forceStableConnectionQueues()

Preserve topology-stable multi-producer admission even for a fixed thread assignment. Configure before initialize() when an out-of-band transport replaces physical connection fanout.

function finalize

void finalize()

End this session. Calls every successfully initialized unit's finalize() once, in creation order, even if another finalizer throws. Idempotent. Call explicitly to observe finalizer failures; destruction is best effort. Host-only, between runs. A finalized simulation cannot be run again.

function epochFreeRunCount

inline uint64_t epochFreeRunCount() const

Number of epoch-free scheduler invocations. Sequential fallback leaves this unchanged, making the counter useful for safety-gate coverage.

function drainCdc

uint64_t drainCdc(
    uint64_t max_event_batches
)

Call after stopping producers; includes RAM, output registers and pointer synchronization.

function domainCycleCount

uint64_t domainCycleCount(
    ClockDomainId id
) const

function dependencyGraph

inline const DependencyGraph & dependencyGraph() const

function currentCycle

inline uint64_t currentCycle() const

function createUnitWithParameters

template <typename UnitT ,
typename ParameterSetT >
inline UnitT * createUnitWithParameters(
    std::unique_ptr< ParameterSetT > parameters
)

Construct a unit from parameters owned by this simulation. Parameters outlive every unit destructor and are released when the simulation ends. A failed creation releases only that attempt's parameters.

function createUnitInDomain

template <typename UnitT ,
typename... Args>
inline UnitT * createUnitInDomain(
    ClockDomainId id,
    Args &&... args
)

function createUnit

template <typename UnitT ,
typename... Args>
inline UnitT * createUnit(
    Args &&... args
)

function connectAsyncFifo

template <typename T >
inline AsyncFifo< T > * connectAsyncFifo(
    uint32_t id,
    AsyncWritePort< T > & write,
    AsyncReadPort< T > & read,
    AsyncFifoConfig config ={}
)

function connect

template <typename T >
inline Connection< T > * connect(
    OutPort< T > & from,
    InPort< T > & to,
    uint32_t delay =1
)

function configureObservation

void configureObservation(
    const observe::ObservationYAMLConfig & config
)

Own the process observation backend for this session. Configure before initialize(). Observed sessions are exclusive; multiclock uses configureClockTrace instead.

function configureClockTrace

void configureClockTrace(
    observe::ClockTraceRecorder::Config config
)

function closeClockTrace

void closeClockTrace()

function clockTraceRecorder

inline observe::ClockTraceRecorder * clockTraceRecorder()

function clockSchedulerProfile

inline const std::vector< ClockSchedulerProfile > & clockSchedulerProfile() const

Host-only, between run calls. Empty unless profile_clock_scheduler is enabled.

function clockPartitionTimeNs

inline uint64_t clockPartitionTimeNs() const

function clockDomain

const ClockDomain & clockDomain(
    ClockDomainId id
) const

function cdcDrained

bool cdcDrained() const

function bindTreeNode

void bindTreeNode(
    Unit & unit,
    tree::TreeNode & node
)

function assignedThread

size_t assignedThread(
    Unit * unit
) const

function assignClockDomain

void assignClockDomain(
    Unit & unit,
    ClockDomainId id
)

function addClockDomain

const ClockDomain & addClockDomain(
    ClockDomain domain
)

Static configuration only. ID 0 is the legacy default clock; UINT32_MAX is reserved.

function TickSimulation

explicit TickSimulation(
    const TickSimulationConfig & config ={}
)

function TickSimulation

TickSimulation(
    const TickSimulation & 
) =delete

Friends

friend TransparentBroadcastFusionTestAccess

friend struct TransparentBroadcastFusionTestAccess(
    TransparentBroadcastFusionTestAccess 
);

Test-only transparent-broadcast fusion selection inspection.

friend TransitiveDependencyPruneTestAccess

friend struct TransitiveDependencyPruneTestAccess(
    TransitiveDependencyPruneTestAccess 
);

Test-only white-box access for transitive dependency pruning.

friend SchedulerScratchTestAccess

friend struct SchedulerScratchTestAccess(
    SchedulerScratchTestAccess 
);

friend PredecessorCycleCacheTestAccess

friend struct PredecessorCycleCacheTestAccess(
    PredecessorCycleCacheTestAccess 
);

Test-only white-box access for test_predecessor_cycle_cache.

friend LookaheadFloorTestAccess

friend struct LookaheadFloorTestAccess(
    LookaheadFloorTestAccess 
);

Test-only white-box access for test_lookahead_floor_progress.

friend EpochFreeDifferentialTestAccess

friend struct EpochFreeDifferentialTestAccess(
    EpochFreeDifferentialTestAccess 
);

Test-only safe-point migration used by the epoch-free differential harness. The seam is intentionally outside the worker hot path.

friend DynamicMigrationTestAccess

friend struct DynamicMigrationTestAccess(
    DynamicMigrationTestAccess 
);

Test-only source-owner migration commit validation.

friend ClockScalingTestAccess

friend struct ClockScalingTestAccess(
    ClockScalingTestAccess 
);

---

Updated on 2026-09-20 at 14:23:39 +0000