Events

event

Events and the event queue.

Priority

Bases: IntEnum

Conventional priorities. Lower values run first among same-time events.

Event

Event(event_type: str = 'event', payload: dict[str, Any] | None = None, callback: EventCallback | None = None, priority: int = Priority.NORMAL)

Something that happens at a point in simulation time.

Use it directly with a callback or subclass it and override :meth:execute. event_id and timestamp are assigned when the event is scheduled.

Ordering is fully deterministic: events execute by (timestamp, priority, scheduling order); lower priority values run first.

execute

execute(sim: Simulation) -> None

Run the event's behaviour. Subclasses override this.

EventQueue

EventQueue()

Binary-heap event queue with lazy cancellation.

Heap entries are (time, priority, seq, event). seq is unique and monotonically increasing, so ties are broken by scheduling order and events themselves are never compared. Cancelling or rescheduling marks the old entry stale instead of searching the heap (O(1)); stale entries are discarded when they reach the top.

discard

discard(event: Event) -> None

Mark a scheduled event as cancelled; its heap entry becomes stale.

pop_due

pop_due(horizon: float) -> Event | None

Pop the next live event if its time is <= horizon, else return None.

peek_time

peek_time() -> float

Time of the next live event, or inf when empty.