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).

Python class

DeviceQueue

DeviceQueue

class max.driver.DeviceQueue(device: max.driver.Device)

source

Bases: object

Provides access to a queue of execution on a device.

A queue represents a sequence of operations that will be executed in order. Multiple queues on the same device can execute concurrently.

from max import driver
device = driver.Accelerator() if driver.accelerator_count() else driver.CPU()
queue = device.default_queue
new_queue = driver.DeviceQueue(device)

Creates a new queue of execution associated with the device.

Parameters:

device – The device to create the queue on.

device

property device

source

The device this queue is executing on.

native_stream_handle

property native_stream_handle

source

The native stream handle as an integer, or 0 if there is none.

The handle is the CUDA CUstream / HIP hipStream_t; 0 means the stream has no native handle (such as a CPU device). Native code outside MLRT can use the handle to order its own work against this stream, for example by recording a CUDA event on it. The handle remains owned by this stream; do not destroy it.

Returns:

The native stream handle, or 0 if there is none.

record_event()

record_event() → max.driver.DeviceEvent

source

Overloaded function.

Overload 1: record_event() -> DeviceEvent

Records an event on this queue.

Returns:

A new event that will be signaled when all operations submitted to this queue before this call have completed.

Raises:

ValueError – If recording the event failed.

Overload 2: record_event(event: DeviceEvent) -> None

Records an existing event on this queue.

Parameters:

event – The event to record on this queue.

Raises:

ValueError – If recording the event failed.

synchronize()

synchronize() → None

source

Ensures all operations on this queue complete before returning.

Raises:

ValueError – If any enqueued operations had an internal error.

wait_for()

wait_for(stream: max.driver.DeviceQueue) → None

source

Overloaded function.

Overload 1: wait_for(stream: DeviceQueue) -> None

Ensures all operations on the other queue complete before future work submitted to this queue is scheduled.

Parameters:

stream – The queue to wait for.

Overload 2: wait_for(device: Device) -> None

Ensures all operations on the device’s default queue complete before future work submitted to this queue is scheduled.

Parameters:

device – The device whose default queue to wait for.

wait_for_host_value()

wait_for_host_value(flag: max.driver.CompletionFlag, value: int) → None

source

Stalls the queue until flag’s 64-bit value equals value.

Wraps the MLRT DeviceStream::enqueueWaitOnHostValue primitive (CUDA’s cuStreamWaitValue64). Typically paired with Device.__unsafe_enqueue_async_py_host_func to gate downstream GPU work on a host-side AsyncRT task that signals flag when it finishes – a queue-internal sync that avoids a host synchronize() and captures cleanly into a CUDA graph as a wait-value node.

Parameters:

• flag – The completion flag to wait on. The queue observes flag.device_ptr via the pinned device-mapped alias.
• value – The 64-bit value to wait for (equality).

Raises:

RuntimeError – If the underlying device does not support stream memory ops, or if the driver rejects the enqueue.