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(self, 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()
# Get the default queue for the device
queue = device.default_queue
# Create a new queue of execution on the device
new_queue = driver.DeviceQueue(device)

Creates a new queue of execution associated with the device.

Parameters:

device (Device) – The device to create the queue on.

Returns:

A new queue of execution.

Return type:

DeviceQueue

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 (e.g. a CPU device). Lets native code outside MLRT order its own work against this stream – for example, record 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.

Return type:

int

record_event()

record_event(self) → max.driver.DeviceEvent

source

record_event(self, event: max.driver.DeviceEvent) → None

Overloaded function.

1. record_event(self) -> max.driver.DeviceEvent

   Records an event on this queue. Returns: : DeviceEvent: 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.

2. record_event(self, event: max.driver.DeviceEvent) -> None

   Records an existing event on this queue.

   Args:

   event (DeviceEvent): The event to record on this queue.

   Raises:

   ValueError: If recording the event failed.

synchronize()

synchronize(self) → 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(self, stream: max.driver.DeviceQueue) → None

source

wait_for(self, device: max.driver.Device) → None

Overloaded function.

1. wait_for(self, stream: max.driver.DeviceQueue) -> None

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

   Args:

   stream (DeviceQueue): The queue to wait for.

2. wait_for(self, device: max.driver.Device) -> None

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

   Args:

   device (Device): The device whose default queue to wait for.

wait_for_host_value()

wait_for_host_value(self, 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 (CompletionFlag) – The completion flag to wait on. The queue observes flag.device_ptr via the pinned device-mapped alias.
• value (int) – 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.