For the complete documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /get-started.md).

Mojo struct

Signal

struct Signal

A synchronization primitive for coordinating GPU thread blocks across multiple devices.

This struct provides counter-based synchronization between thread blocks on different GPUs. It maintains two sets of counters:

1. self_counter: Used by blocks on the current GPU to signal their progress
2. peer_counter: Used to track progress of blocks on other GPUs

Note: The counters use unsigned integers that may overflow, but this is safe since unsigned integer overflow has well-defined behavior.

Fields

• ​self_counter (StaticTuple[StaticTuple[StaticTuple[UInt32, Int(8)], Int(1024)], Int(8)]): A 3D array of counters with shape (NUM_BARRIER_DOMAINS, MAX_NUM_BLOCKS_UPPER_BOUND, MAX_GPUS). Each counter tracks the progress of a specific thread block on the current GPU for a domain. Thread blocks increment their corresponding counter to signal completion of a phase, allowing other GPUs to detect when synchronization points are reached. The counters use atomic operations to ensure proper synchronization across devices.

• ​peer_counter (StaticTuple[StaticTuple[StaticTuple[StaticTuple[UInt32, Int(8)], Int(1024)], Int(2)], Int(8)]): A 4D array of counters with shape (NUM_BARRIER_DOMAINS, 2, MAX_NUM_BLOCKS_UPPER_BOUND, MAX_GPUS). Each domain contains two sets of counters to handle two synchronization points safely. The dual counter design prevents race conditions where a peer block arrives at the second sync point before the current block passes the first sync point.

• ​lamport_state (StaticTuple[UInt32, Int(4)]): Device-resident state for the in-kernel Lamport generation advance: [flag, prev_num_packs, arrival, reserved].

  • flag: monotonically-increasing generation counter (read at kernel entry, advanced once per call in the grid-barrier epilogue).
  • prev_num_packs: previous call's written extent in 16-byte packs = this call's clear extent (dtype-independent, so mixed-dtype call sequences on one signal buffer clear exactly what was written).
  • arrival: per-call block-arrival counter for the exactly-once advance.
  • reserved: pads to 16 bytes so lamport_region stays 16-byte aligned (the 128-bit atomic stores require it).

  Zero-fill is the correct start state (flag 0, nothing to clear). This is the sole source of the generation counter / clear extent -- the kernel reads and advances it in-kernel, so the public op needs no per-call argument.

• ​lamport_region (StaticTuple[UInt8, Int(25165824)]): The barrier-free Lamport comm region: 3 rotating generations x MAX_GPUS rank slots x the per-slot max message. Disjoint from self_counter & peer_counter to enable a mix of lamport & barrier-based collectives on the same signal buffer.

Implemented traits

AnyType, Deinitable, Movable

comptime members

flag_t

comptime flag_t = DType.uint32

Methods

unsafe_ptr_from

static def unsafe_ptr_from(mut signal_buffer: DeviceBuffer[.uint8]) -> Pointer[Self, MutAnyOrigin]

Reinterprets a rank's signal buffer as a Signal pointer.

The collectives take their rank_sigs as Signal pointers while the host allocates each rank's buffer as raw bytes, so every call site assembling a rank_sigs array otherwise repeats this same cast.

The borrow is mutable because DeviceBuffer.unsafe_ptr ties the returned pointer's mutability to it, and a collective writes through rank_sigs.

Safety: The returned pointer's origin is erased, so it does not keep signal_buffer alive. The buffer must outlive every collective launched against the pointer.

Args:

• ​signal_buffer (DeviceBuffer[.uint8]): This rank's signal buffer, at least size_of[Signal]() bytes and already passed through init_signal_buffer.

Returns:

Pointer[Self, MutAnyOrigin]: A pointer to the buffer's storage, typed as Signal.

lamport_state_ptr

def lamport_state_ptr(mut self) -> Pointer[UInt32, MutAnyOrigin]

Typed pointer to this Signal's lamport_state block.

Index it with the Lamport.STATE_* constants. The field is located by its own address (Pointer(to=...)), so there is no hand-computed byte offset to keep in sync with the field order.

Returns:

Pointer[UInt32, MutAnyOrigin]

lamport_region_ptr

def lamport_region_ptr[dtype: DType](mut self) -> Pointer[Scalar[dtype], MutAnyOrigin]

Typed pointer to the start of this Signal's embedded Lamport region.

Parameters:

• ​dtype (DType): The element type to reinterpret the raw region bytes as. The returned pointer is typed Pointer[Scalar[dtype], ...] so callers can read and write Lamport message packs in this dtype without an extra cast.

Returns:

Pointer[Scalar[dtype], MutAnyOrigin]