chronon::Connection

#include <Connection.hpp>

Inherits from chronon::sender::ConnectionBase

Public Functions

	Name
bool	transfer(T data, uint64_t send_cycle)
InPort< T > *	to() const
virtual Unit *	source() const override
virtual void	setThreadQueueId(size_t queue_id) override
virtual void	setConnId(uint32_t conn_id) override
virtual size_t	registerProducerThread(size_t thread_id) override
virtual IArbitratablePort *	registerOnDestMPSC() override
virtual void	optimizeForSameThread() override
virtual void	optimizeForSPSC() override
virtual void	optimizeForMPSC() override
virtual std::optional< uint64_t >	minStagedArrivalCycle() const override Earliest arrival currently staged on this MPSC connection, if any.
bool	isDestinationFull() const
virtual bool	hasThreadQueueId() const override True if this connection uses thread-specific queue (MPSC mode).
OutPort< T > *	from() const
virtual bool	ensureEpochFreeHeadroom(uint32_t max_lookahead_cycles) override
virtual Unit *	destination() const override
virtual void *	destPortPtr() const override
virtual uint32_t	delay() const override
virtual size_t	crossThreadHeadroom() const override
virtual uint32_t	connId() const override
virtual void	configureRegisteredEdge(std::optional< size_t > capacity, std::optional< size_t > rate) override
virtual void	cancelInFlight() override
bool	canTransfer() const True if the destination can accept data (back-pressure preflight).
virtual size_t	arbitrateAdmitErased(size_t budget) override
virtual size_t	arbitrateAdmitBoundedErased(size_t budget, uint64_t max_send_cycle) override
	Connection(OutPort< T > * from, InPort< T > * to, uint32_t delay)

Additional inherited members

Public Functions inherited from chronon::sender::ConnectionBase

	Name
virtual	~ConnectionBase() =default
bool	isTight() const True if this is a zero-delay (tight) connection.

Detailed Description

template <typename T >
class chronon::Connection;

Connection - Typed connection between OutPort and InPort.

Connections specify the communication delay:

delay=0: Tight coupling, same-cycle delivery on acyclic paths
delay>0: Loose coupling, future delivery (lookahead possible)

Usage: auto conn = sim.connect(producer->out, consumer->in, 5); // Messages sent at cycle N arrive at cycle N+5

Public Functions Documentation

function transfer

inline bool transfer(
    T data,
    uint64_t send_cycle
)

Parameters:

data The data to transfer
send_cycle The current cycle when sending

Return: true if transfer succeeded, false if destination full (back pressure)

Transfer data through the connection.

The data will arrive at the destination port after the configured delay. Uses thread-specific queue if in multi-producer mode.

function to

inline InPort< T > * to() const

function source

virtual Unit * source() const override

Reimplements: chronon::sender::ConnectionBase::source

function setThreadQueueId

inline virtual void setThreadQueueId(
    size_t queue_id
) override

Parameters:

queue_id The queue ID for this connection

Reimplements: chronon::sender::ConnectionBase::setThreadQueueId

Set the thread queue ID for multi-producer mode.

Called during initialization when the destination InPort is in multi-producer mode.

function setConnId

inline virtual void setConnId(
    uint32_t conn_id
) override

Reimplements: chronon::sender::ConnectionBase::setConnId

Stable connection identifier assigned at simulation build time.

Equal to this connection's index in TickSimulation::connections_. Used by MultiProducerQueueAdapter as a cross-num_workers-stable tiebreaker in the k-way merge, replacing the partition-dependent queue_id. The value is deterministic given a fixed topology, regardless of thread count / cluster assignment.

function registerProducerThread

inline virtual size_t registerProducerThread(
    size_t thread_id
) override

Parameters:

thread_id Stable producer key. TickSimulation passes conn_id + 1.

Return: Queue ID for this producer key, or SIZE_MAX on failure

Reimplements: chronon::sender::ConnectionBase::registerProducerThread

function registerOnDestMPSC

virtual IArbitratablePort * registerOnDestMPSC() override

Reimplements: chronon::sender::ConnectionBase::registerOnDestMPSC

Register this MPSC connection on its destination InPort and return the InPort's type-erased IArbitratablePort interface so the TickSimulation can drive cycle-boundary arbitration without ever knowing the Connection's message type. Returns nullptr when the connection is not in MPSC mode.

function optimizeForSameThread

inline virtual void optimizeForSameThread() override

Reimplements: chronon::sender::ConnectionBase::optimizeForSameThread

Optimize destination port for same-thread access.

Switches InPort to use lock-free SingleThreadMessageQueue. Call this during initialization when both source and destination are determined to be on the same thread (same cluster).

This keeps intra-cluster registered edges on the cheapest storage.

function optimizeForSPSC

inline virtual void optimizeForSPSC() override

Reimplements: chronon::sender::ConnectionBase::optimizeForSPSC

Optimize destination port for cross-thread SPSC access.

Switches InPort to use lock-free LockFreeMessageQueue. Call this during initialization when there is exactly ONE source thread writing to the destination port on a different thread.

function optimizeForMPSC

inline virtual void optimizeForMPSC() override

Reimplements: chronon::sender::ConnectionBase::optimizeForMPSC

Optimize destination port for cross-thread MPSC access.

Switches InPort to use MultiProducerQueueAdapter with one producer queue per Connection.

function minStagedArrivalCycle

inline virtual std::optional< uint64_t > minStagedArrivalCycle() const override

Earliest arrival currently staged on this MPSC connection, if any.

Reimplements: chronon::sender::ConnectionBase::minStagedArrivalCycle

function isDestinationFull

inline bool isDestinationFull() const

function hasThreadQueueId

inline virtual bool hasThreadQueueId() const override

True if this connection uses thread-specific queue (MPSC mode).

Reimplements: chronon::sender::ConnectionBase::hasThreadQueueId

function from

inline OutPort< T > * from() const

function ensureEpochFreeHeadroom

inline virtual bool ensureEpochFreeHeadroom(
    uint32_t max_lookahead_cycles
) override

Reimplements: chronon::sender::ConnectionBase::ensureEpochFreeHeadroom

Try to grow physical lock-free buffers enough for epoch-free run-ahead when the model-visible registered edge is unbounded. A finite declared edge capacity is semantic backpressure and must not be bypassed by resizing the storage ring.

function destination

virtual Unit * destination() const override

Reimplements: chronon::sender::ConnectionBase::destination

function destPortPtr

inline virtual void * destPortPtr() const override

Reimplements: chronon::sender::ConnectionBase::destPortPtr

function delay

inline virtual uint32_t delay() const override

Reimplements: chronon::sender::ConnectionBase::delay

function crossThreadHeadroom

inline virtual size_t crossThreadHeadroom() const override

Reimplements: chronon::sender::ConnectionBase::crossThreadHeadroom

Max producer run-ahead (in cycles) this connection's cross-thread buffer (MPSC staging ring or SPSC lock-free ring) can absorb while the epoch-free path keeps results identical to the reference: roughly threshold / rate - delay + 1, where threshold is the entry count at which transfer() stops accepting (the ring, or the InPort capacity if smaller), rate is the source's per-cycle send cap, and delay accounts for not-yet-due entries the consumer cannot drain. Returns SIZE_MAX for connections with no bounded cross-thread ring (same-thread / unbounded) and 0 when no finite capacity dependency is provably safe. Used to gate the epoch-free lookahead path, which removes the per-epoch drain.

function connId

inline virtual uint32_t connId() const override

Reimplements: chronon::sender::ConnectionBase::connId

function configureRegisteredEdge

inline virtual void configureRegisteredEdge(
    std::optional< size_t > capacity,
    std::optional< size_t > rate
) override

Reimplements: chronon::sender::ConnectionBase::configureRegisteredEdge

Configure the registered edge modeled by this connection. capacity is the number of entries the producer may have in flight on this edge; rate is the maximum entries this edge can accept per producer cycle.

function cancelInFlight

inline virtual void cancelInFlight() override

Reimplements: chronon::sender::ConnectionBase::cancelInFlight

Cancel all in-flight messages previously sent on this connection.

Only bumps the cancellation epoch. Staged entries are dropped lazily by the arbiter on drain (it compares each entry's epoch_snapshot against the current epoch). This matters under consumer-tick-driven arbitration (Option 1): the producer thread and the consumer-thread arbiter may access staging_ concurrently, so a producer-side staging_.clear() would race with the arbiter's drain. See R3 in docs/mpsc-atomic-publish.md.

function canTransfer

inline bool canTransfer() const

True if the destination can accept data (back-pressure preflight).

function arbitrateAdmitErased

inline virtual size_t arbitrateAdmitErased(
    size_t budget
) override

Reimplements: chronon::sender::ConnectionBase::arbitrateAdmitErased

Type-erased MPSC admission helper invoked by the InPort arbiter.

Unbounded drain variant: drains every staging entry whose epoch matches the current cancel_epoch_. Called by the main-thread arbiter path (Sequential per-cycle loop, Barrier sync_wait, lookahead epoch-end flush).

function arbitrateAdmitBoundedErased

inline virtual size_t arbitrateAdmitBoundedErased(
    size_t budget,
    uint64_t max_send_cycle
) override

Reimplements: chronon::sender::ConnectionBase::arbitrateAdmitBoundedErased

Cycle-bounded admission: drains every staging entry whose epoch matches AND whose enqueue_cycle <= max_send_cycle. Used by the consumer-tick-driven arbiter (Option 1): the consumer at its own localCycle computes S = min(predecessor-thread completed_cycle) and passes S here, so only entries that every producer has finished writing are admitted this tick.

function Connection

inline Connection(
    OutPort< T > * from,
    InPort< T > * to,
    uint32_t delay
)

Parameters:

from Source output port
to Destination input port
delay Number of cycles for message delivery

Create a connection with specified delay.

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

Public Functions​

Additional inherited members​

Detailed Description​

Public Functions Documentation​

function transfer​

function to​

function source​

function setThreadQueueId​

function setConnId​

function registerProducerThread​

function registerOnDestMPSC​

function optimizeForSameThread​

function optimizeForSPSC​

function optimizeForMPSC​

function minStagedArrivalCycle​

function isDestinationFull​

function hasThreadQueueId​

function from​

function ensureEpochFreeHeadroom​

function destination​

function destPortPtr​

function delay​

function crossThreadHeadroom​

function connId​

function configureRegisteredEdge​

function cancelInFlight​

function canTransfer​

function arbitrateAdmitErased​

function arbitrateAdmitBoundedErased​

function Connection​

Public Functions

Additional inherited members

Detailed Description

Public Functions Documentation

function transfer

function to

function source

function setThreadQueueId

function setConnId

function registerProducerThread

function registerOnDestMPSC

function optimizeForSameThread

function optimizeForSPSC

function optimizeForMPSC

function minStagedArrivalCycle

function isDestinationFull

function hasThreadQueueId

function from

function ensureEpochFreeHeadroom

function destination

function destPortPtr

function delay

function crossThreadHeadroom

function connId

function configureRegisteredEdge

function cancelInFlight

function canTransfer

function arbitrateAdmitErased

function arbitrateAdmitBoundedErased

function Connection