KSLCore/ksl.animation/ReplicationSelectingSink

ReplicationSelectingSink

class ReplicationSelectingSink(delegate: AnimationSink, capturedReplications: Set<Int>) : AnimationSink(source)

A filtering AnimationSink that forwards events and lifecycle callbacks to delegate only during the replications named in capturedReplications.

Animating an entire multi-replication experiment is rarely wanted; a modeler typically animates one replication. This decorator restricts capture to the chosen replication number(s). During any non-selected replication isActive is false, so — by the usual if (sink.isActive) sink.emit(...) rule — no event objects are constructed and that replication costs nothing.

The delegate sees a clean lifecycle for the selected replications only: its onReplicationStart/onReplicationEnd fire just for those, so a buffering delegate flushes exactly one batch per selected replication and is never asked to flush an empty non-selected one. onExperimentEnd is always forwarded so a delegate that owns an experiment-scoped resource (e.g. an open file) can close it.

Parameters

delegate

the downstream sink that records events for selected replications

capturedReplications

the 1-based replication numbers to capture (non-empty)

Constructors

ReplicationSelectingSink

constructor(delegate: AnimationSink, capturedReplications: Set<Int>)

constructor(delegate: AnimationSink, replication: Int)

Convenience constructor for capturing a single replication.

Properties

isActive

open override val isActive: Boolean

Whether this sink is collecting events. Emission sites must check this before building and emitting an event. A false value must be a cheap, branch-predictable constant.

Functions

emit

open override fun emit(event: AnimationEvent)

Records event. Called only when isActive is true. Must not throw on the simulation thread; implementations should fail soft (e.g. drop and log) rather than disrupt the run.

onExperimentEnd

open override fun onExperimentEnd()

Called once after the final replication of the experiment.

onReplicationEnd

open override fun onReplicationEnd(replicationNumber: Int)

Called at the end of replication replicationNumber (1-based).

onReplicationStart

open override fun onReplicationStart(replicationNumber: Int)

Called at the start of replication replicationNumber (1-based).