SystemVerilog Reference

mailbox

A mailbox is a FIFO between processes. put adds a message and get waits for one.

Syntax

mailbox #(int) mb = new(2);   // holds at most 2; new() is unbounded
mb.put(v);       // waits while the mailbox is full
mb.get(v);       // waits while it is empty

Rules

  • put and get block. try_put and try_get return at once with 1 or 0.
  • peek copies the first message and leaves it in the mailbox.
  • num() returns how many messages are waiting.
  • Give the mailbox a type, mailbox #(T), so a wrong type is a compile error.
  • A bounded mailbox applies backpressure: the producer waits when it is full.

Example

module tb;
  mailbox #(int) mb = new(1);

  initial begin
    for (int i = 1; i <= 3; i++) begin
      mb.put(i);
      $display("t=%0t put %0d", $time, i);
    end
  end

  initial begin
    int v;
    repeat (3) begin
      #10 mb.get(v);
      $display("t=%0t got %0d", $time, v);
    end
  end
endmodule
Output on Verilator 5.052
t=0 put 1
t=10 got 1
t=10 put 2
t=20 got 2
t=20 put 3
t=30 got 3

Run It in the Playground

Common Mistake

Putting the same object every time

tr = new();
repeat (3) begin
  tr.randomize();
  mb.put(tr);   // three handles to one object
end

A mailbox stores handles, not copies. All three entries point to one object, which holds the last values.

Fix: Create a new object inside the loop, or put a copy.

Learn It Properly

These lessons teach it step by step, with practice problems.

Standard

IEEE 1800-2023, 15.4.