Core
Core simulation primitives: Environment, Event, Interrupt, Timeout, Process.
Environment
Discrete-event simulation environment.
Maintains two queues: - _ready: callbacks to run at the current simulated time (deque). - _heap: callbacks scheduled for a future time (min-heap).
The clock only advances when popping from _heap; _ready is always drained first. This prevents zero-delay events from racing ahead of same-time future events and ensures FIFO ordering among simultaneous events.
now
property
Current simulation time.
immediate(cb)
Schedule cb for execution at the current simulated time.
log(name, message)
Record a log message.
run(until=None)
Run the simulation.
Runs until no events remain, or until simulated time reaches until.
schedule(time, cb)
Schedule cb to run at time in the future.
timeout(delay)
Return a Timeout event for delay time units.
Event
An awaitable simulation event.
Primitives such as Queue.get() return Event objects. Processes suspend themselves by awaiting an Event:
item = await queue.get()
An Event transitions through these states (stored in _value): _PENDING: not yet triggered any value: triggered with that value (including None) _CANCELLED: cancelled; _on_cancel was called if set
The _on_cancel callback is called by cancel() even when the event has already been triggered. This lets resource-consuming get() methods restore their resource when FirstOf discards a non-winning event.
cancelled
property
True if the event has been cancelled.
triggered
property
True if the event has been triggered (not pending, not cancelled).
cancel()
Cancel the event.
Fires _on_cancel(old_value) regardless of whether the event was pending or already triggered. This ensures that resources consumed by a pre-triggered get event are restored when FirstOf discards it. Does nothing if the event is already cancelled.
fail(exc)
Trigger the event with an exception.
The process awaiting this event will re-raise exc.
succeed(value=None)
Trigger the event with value and notify all waiters.
Interrupt
Process
Bases: ABC
Abstract base class for all simulation processes.
Subclasses implement run() as an async method. Optionally override init() for setup that must happen before the coroutine is created.
now
property
Shortcut to the current simulation time.
init(*args, **kwargs)
Optional subclass setup hook, called before the coroutine is created.
interrupt(cause=None)
Throw an Interrupt into this process.
The Interrupt is delivered at the process's current await point. Has no effect if the process has already finished.
log(name, message)
Record a log message in the environment.
resume(value=None)
Called by an Event when it triggers; re-schedules _loop.
Uses functools.partial (a C-level callable) to avoid creating a Python closure, keeping per-resume overhead low.
run()
abstractmethod
async
Implement process behaviour here.
timeout(delay)
Return a Timeout event for delay simulated time units.
Timeout
Bases: Event
An Event that triggers after delay simulated time units.
cancelled
property
True if the event has been cancelled.
triggered
property
True if the event has been triggered (not pending, not cancelled).
cancel()
Cancel the event.
Fires _on_cancel(old_value) regardless of whether the event was pending or already triggered. This ensures that resources consumed by a pre-triggered get event are restored when FirstOf discards it. Does nothing if the event is already cancelled.
fail(exc)
Trigger the event with an exception.
The process awaiting this event will re-raise exc.
succeed(value=None)
Trigger the event with value and notify all waiters.