Chapter 11: Advanced Core Semantics

Source Deep Dive: sc_event_queue

How sc_event_queue models repeated timed notifications and why it is useful for timers, delayed work, and modeling adapters.

20 minLesson 105

How to Read This Lesson

sc_event is a single named event. sc_event_queue is what you reach for when a channel or helper object needs to manage many future notifications through one observable event.

Source and LRM Trail

Use Docs/LRMs/SystemC_LRM_1666-2023.pdf for event and timed notification semantics. In source, inspect .codex-src/systemc/src/sysc/kernel/sc_event_queue.* and the event scheduling machinery in sc_event.* and sc_simcontext.*.

The Problem sc_event_queue Solves

Suppose a peripheral schedules several future interrupts. You could allocate a separate sc_event per interrupt, but that becomes awkward when events are dynamic.

sc_event_queue lets you do this:

SC_MODULE(Device) {
  sc_core::sc_event_queue irq_queue;
 
  SC_CTOR(Device) {
    SC_METHOD(on_irq);
    sensitive << irq_queue.default_event();
    dont_initialize();
  }
 
  void schedule_irq(sc_core::sc_time delay) {
    irq_queue.notify(delay);
  }
 
  void on_irq() {
    std::cout << "IRQ event at " << sc_core::sc_time_stamp() << "\n";
  }
};

The user-facing mental model is simple: every notify(delay) schedules work, and the queue exposes a default event that fires when the next queued notification matures.

How the Source Makes This Work

Internally, an event queue manages timed notifications and exposes a single event-like interface to the rest of the model. It is a helper around the same scheduler idea you already know: future work is stored until simulation time reaches the scheduled point.

The important distinction is that sc_event generally has one pending timed notification state, while an event queue is designed for multiple queued notifications.

Where This Shows Up in Real Models

Use an event queue for:

  • delayed peripheral interrupts
  • modeling timer compare events
  • retry scheduling after bus contention
  • adapters that convert external timestamps into SystemC events
  • rate-limited callbacks where several future activations may already be known

Avoid it when a normal sc_event or wait(delay) is enough. Extra scheduling machinery makes the model harder to reason about if you do not need it.

Review Checklist

  • Can more than one future notification be pending?
  • Is the default event used for sensitivity instead of exposing internals?
  • Are events canceled or allowed to drain deliberately?
  • Does the model document whether multiple notifications at the same timestamp collapse or produce repeated activations?
  • Would a normal sc_event be clearer?

Comments and Corrections