Skip to content

API Reference — Mailbox — receive

New to the concept? See Building Blocks — Mailbox first.

receive

Before                           After

receiver Slot                    receiver Slot
+-------------------+            +-------------------+
|       null        |            |    ItemHandle     |
+-------------------+            +-------------------+

mailbox.receive(mbh, &slot, null)   Receiver holds ItemHandle

pub fn receive(mbh: MailboxHandle, slot: *Slot, timeout_ns: ?u64) (error{ Closed, Timeout, Wakeup } || Cancelable)!void
  • Blocks until handle available.
  • null timeout = wait forever.
  • timeout_ns = 0 returns error.Timeout immediately — equivalent to try_receive.
  • Moves the handle — slot.* set to non-null.
  • OOB handles arrive first (front of queue).
  • wakeUpAll() called while blocked here — returns error.Wakeup, slot.* stays null.
  • Multiple concurrent receivers compete for each handle.
  • One receiver gets it.
  • Order among waiters depends on the Io runtime — not guaranteed FIFO.
  • Assert:
  • mailbox.is_it_you(mbh.*.tag)
  • slot.* == null

try_receive

pub fn try_receive(mbh: MailboxHandle, slot: *Slot) error{Closed}!bool
  • Non-blocking.
  • Returns true if handle received, false if queue empty.
  • Assert:
  • mailbox.is_it_you(mbh.*.tag)
  • slot.* == null

receive_batch

pub fn receive_batch(mbh: MailboxHandle) error{Closed}!std.DoublyLinkedList
  • Non-blocking.
  • Takes everything from the queue at once.
  • Returns empty std.DoublyLinkedList if queue is currently empty.
  • Does not wait. Does not return error for empty.
  • Assert:
  • mailbox.is_it_you(mbh.*.tag)

Next: wakeUpAll / close / destroy / is_it_you.