Skip to main content

chronon::sender::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
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
voidinstallMPSCProducerProgress_()
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
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
structLookaheadFloorTestAccess
Test-only white-box access for test_lookahead_floor_progress.

Detailed Description​

class chronon::sender::TickSimulation;

High-performance simulation using stdexec.

Execution model: Chronon selects sequential, barrier, or lookahead at runtime. In lookahead mode, tight clusters advance on dependency progress atomics; epoch-free lookahead is the default when the safety gate can prove that no per-epoch flush is required. The older per-epoch lookahead fallback is deprecated and kept only as a compatibility/safety fallback.

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

inline uint64_t totalStagingOverflowEvents() const

Total dropped staged pushes across all MPSC InPorts (full physical ring). Nonzero means the lookahead window outran the staging capacity — a correctness failure. The epoch-free A/B watchdog (see enable_epoch_free_lookahead). Always 0 for the barrier/sequential paths.

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

void installMPSCProducerProgress_()

Resolve the producer-cluster completed_cycle atomics for each MPSC InPort. Lookahead-only; under Sequential/Barrier the producer- progress set stays empty and arbitrateMPSCConsumerDriven() degrades to an unbounded drain (correct because those modes only call the consumer-driven hook after a global sync point).

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

inline uint64_t epochFreeRunCount() const

Number of runParallel() invocations that took the epoch-free path. Test/bench introspection for the enable_epoch_free_lookahead A/B knob.

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

friend struct LookaheadFloorTestAccess(
    LookaheadFloorTestAccess 
);

Test-only white-box access for test_lookahead_floor_progress.

Updated on 2026-07-06 at 09:03:33 +0000