KSLCore/ksl.animation/EntityCaptureFilteringSink

EntityCaptureFilteringSink

class EntityCaptureFilteringSink(downstream: AnimationSink, excludedTypes: Set<String>, excludedProcesses: Set<String>) : AnimationSink(source)

A filtering AnimationSink that drops an entity's events when its type or its current process is excluded from capture (Phase 10.1d). A decorator in the same family as WindowedAnimationSink: it wraps a downstream sink and removes events without the producers (or that sink) knowing anything about it.

Entity/process events are emitted unconditionally by the engine (they bypass the structural registration gate), so capture selection for them is applied here. Filtering is exclusion-only: an event is dropped only when its type is in excludedTypes or its current process is in excludedProcesses. With both sets empty (the default), nothing is dropped — so default capture-all and structural SELECTED mode are unaffected (this filter does not impose the structural include-list on entities).

Identity is recovered from the trace by the same normalization the viewer uses (decision F7): the entity's type is learned from its EntityCreated, and its current process is tracked from ProcessActivated/ProcessCompleted. Process exclusion is keyed by the composite "Type.process" name so identically named processes on different types are distinguished. Lifecycle markers and events not keyed to an entity always pass.

Parameters

downstream

the sink that records events this filter keeps

excludedTypes

type names (matching EntityCreated.entityType) whose events are dropped entirely

excludedProcesses

composite "Type.process" names whose events are dropped while the entity is in that process

Constructors

EntityCaptureFilteringSink

constructor(downstream: AnimationSink, excludedTypes: Set<String>, excludedProcesses: Set<String>)

Properties

filtersAnything

val filtersAnything: Boolean

True when there is anything to exclude; lets callers skip wrapping entirely otherwise.

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