IMPORTANT: To view this page as Markdown, append `.md` to the URL (e.g. /docs/manual/basics.md). For the complete Mojo documentation index, see llms.txt.
Skip to main content
Version: Nightly
For the complete Mojo documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /docs/manual/basics.md).

CompletionFlag

struct CompletionFlag

Non-owning handle to an MLRT CompletionFlag.

A CompletionFlag is an 8-byte slot in pinned host memory mapped into a device's address space. A CPU thread (or an AsyncRT worker dispatched by DeviceStream.enqueue_host_func) writes a 64-bit value to the slot; the GPU side waits on the same slot via DeviceStream.wait_for_host_value. The pairing lets a CUDA stream block on a value produced by a host thread without a second stream or a blocking host callback on the consumer's critical path.

This struct is intentionally non-owning. The C++ M::Driver::CompletionFlag it points to is allocated and freed elsewhere (typically by max.driver.CompletionFlag on the Python side), and the caller is responsible for keeping the underlying allocation alive for the duration of any in-flight use. Constructed from a raw pointer extracted from a graph-op payload buffer; do not allocate or free through this wrapper.

Currently usable only on CUDA-backed devices, matching DeviceStream.wait_for_host_value.

Implemented traits​

AnyType, Copyable, ImplicitlyCopyable, ImplicitlyDestructible, Movable

Methods​

__init__​

def __init__(out self, *, handle: Optional[UnsafePointer[_CompletionFlagCpp, MutExternalOrigin]])

Constructs a non-owning handle from a raw pointer to the C++ M::Driver::CompletionFlag.

Args:

def __init__(out self, *, unsafe_from_address: Int)

Constructs a non-owning handle from an integer address.

Intended for graph-op execute methods that extract a packed pointer from a payload buffer (mirroring how mo.launch_host_func rebuilds its trampoline/user-data pointers). The caller asserts that unsafe_from_address points to a valid M::Driver::CompletionFlag and that the underlying object outlives any in-flight use.

Args:

  • ​unsafe_from_address (Int): Raw address of an M::Driver::CompletionFlag (as packed into a graph payload buffer by the producer side).

device_ptr​

def device_ptr(self) -> UInt64

Returns the device-visible 64-bit address of the flag's slot.

This is the same value the host-side signal() writes through and that the GPU's cuStreamWaitValue64 polls.

Returns:

UInt64: Device-visible address of the 8-byte slot.

View source