Skip to main content

chronon::TickSimulation

More...

#include <TickSimulation.hpp>

Public Functions​

Name
~TickSimulation()
voidwriteTimelineTrace()
Write the scheduler execution timeline at end of run.
boolwasTerminationRequested() const
booluseParallelExecution() const
size_tunitCount() const
size_ttransparentBroadcastConnectionCount() const
uint64_ttotalTransportOverflowEvents() const
uint64_ttotalStagingOverflowEvents() const
const std::string &timelineTraceFile() const
booltimelineTraceEnabled() const
uint64_ttickFrequencyHz() const
const TerminationRequest &terminationRequest() const
Only valid after runUntilTermination() returns.
voidsetPrecomputedUnitCosts(std::vector< double > unit_costs, PlatformMetrics metrics)
Provide explicit per-unit costs instead of using uniform-cost initial partitioning.
uint64_trunUntilTermination(uint64_t max_cycles =UINT64_MAX)
uint64_trunUntilComplete(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_trun(uint64_t num_cycles)
voidresetTermination()
Reconstructs the stop_source (inplace_stop_source is non-resettable).
voidrequestTermination(TerminationReason reason, int32_t exit_code =0, std::string_view message ="")
Externally-driven termination, e.g. signal handlers or API calls.
voidregisterConnection(ConnectionBase * conn)
uint64_trebalanceCount() const
exec::static_thread_pool &pool()
Used by observation async I/O.
TickSimulation &operator=(const TickSimulation & ) =delete
size_tnormalizeThreadCount(size_t requested)
boolisParallelBeneficial() const
boolisInitialized() const
voidinstallMultiProducerProgress_()
voidinitialize()
boolhasTightConnectionsInGraph() const
stdexec::inplace_stop_tokenget_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
voidforceStableConnectionQueues()
uint64_tepochFreeRunCount() const
const DependencyGraph &dependencyGraph() const
uint64_tcurrentCycle() const
template <typename UnitT ,typename... Args>
UnitT *		createUnit(Args &&... args)
template <typename T >
Connection< T > *		connect(OutPort< T > & from, InPort< T > & to, uint32_t delay =1)
size_tassignedThread(Unit * unit) const
TickSimulation(const TickSimulationConfig & config ={})
TickSimulation(const TickSimulation & ) =delete

Friends​

Name
structTransparentBroadcastFusionTestAccess
Test-only transparent-broadcast fusion selection inspection.
structTransitiveDependencyPruneTestAccess
Test-only white-box access for transitive dependency pruning.
structPredecessorCycleCacheTestAccess
Test-only white-box access for test_predecessor_cycle_cache.
structLookaheadFloorTestAccess
Test-only white-box access for test_lookahead_floor_progress.
structEpochFreeDifferentialTestAccess
structDynamicMigrationTestAccess
Test-only source-owner migration commit validation.

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​

inline ~TickSimulation()

function writeTimelineTrace​

inline 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 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 setPrecomputedUnitCosts​

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

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

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 run​

uint64_t run(
    uint64_t num_cycles
)

Run for the specified cycles. Internally dispatches to parallel or sequential execution based on cluster analysis.

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​

inline void registerConnection(
    ConnectionBase * conn
)

For YAML-driven builders that create connections via type-erased port handles rather than the templated connect() above.

function rebalanceCount​

inline uint64_t rebalanceCount() const

function pool​

inline exec::static_thread_pool & pool()

Used by observation async I/O.

function operator=​

TickSimulation & operator=(
    const TickSimulation & 
) =delete

function normalizeThreadCount​

static inline size_t normalizeThreadCount(
    size_t requested
)

function isParallelBeneficial​

inline bool isParallelBeneficial() const

function isInitialized​

inline bool isInitialized() const

function installMultiProducerProgress_​

void installMultiProducerProgress_()

Resolve one producer-cluster completed-cycle atomic for each direct MPSC lane. Complete coverage is required by epoch-free lookahead.

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​

inline 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 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 dependencyGraph​

inline const DependencyGraph & dependencyGraph() const

function currentCycle​

inline uint64_t currentCycle() const

function createUnit​

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

function connect​

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

function assignedThread​

inline size_t assignedThread(
    Unit * unit
) const

function TickSimulation​

inline 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 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.

Updated on 2026-07-23 at 16:24:33 +0000