Struct Device 

pub struct Device { /* private fields */ }

A Metal GPU with its command queue, kernel library and pipeline cache. Cheap to clone.

Implementations

impl Device

pub fn new_buffer(&self, len: usize) -> Result<Buffer>

A buffer of len bytes from the caching allocator. Its contents are unspecified (a reused buffer holds stale bytes); fails with GpuError::OutOfMemory beyond the memory limit.

pub fn new_gpu_buffer(&self, len: usize) -> Result<Buffer>

A buffer of len bytes for GPU work to write: as new_buffer, but it may be memory that committed GPU work still uses (as MLX reuses memory). GPU work encoded with it is ordered after those uses; the CPU cannot access it until they complete (Buffer::in_use).

pub fn map_file(&self, path: &Path) -> Result<Buffer>

The file at path, memory-mapped read-only and wrapped without a copy (newBufferWithBytesNoCopy): its pages are the page cache’s, read from disk when first touched by the CPU or the GPU. The buffer cannot be written (CPU writes and GPU writes are refused). The mapping is released when the buffer and every GPU use of it are gone.

A shared read-only mapping is used because a private (copy-on-write) one costs about 4× more to fault in on first use.

pub fn buffer_from(&self, bytes: &[u8]) -> Result<Buffer>

A buffer holding a copy of bytes.

impl Device

pub fn command_buffer(&self) -> Result<CommandBuffer>

A new command buffer on this device’s queue.

impl Device

pub fn timeline(&self) -> Result<Timeline>

A new, empty timeline.

pub fn ordered_command_buffer(&self) -> Result<CommandBuffer>

A new command buffer whose work reads the outputs of earlier ordered command buffers (committed on this device from any thread) safely while they are in flight: before a dispatch reads or writes a buffer with a pending GPU write, it waits for the writing command buffer’s fence. Independent command buffers overlap on the GPU, as in MLX.

Reads wait for the pending writer; writes wait for every pending user (writing a buffer that earlier work still reads). Other command buffers do not wait.

pub fn command_buffer_on( &self, timeline: &mut Timeline, ) -> Result<CommandBuffer>

A new command buffer whose work runs after the work of every command buffer created earlier on timeline (commit them in creation order).

impl Device

pub fn system_default() -> Option<Device>

The system’s default Metal device, or None if there is none (for example in some virtual machines).

pub fn shared() -> Option<&'static Device>

The process-wide default device, created on first use: one allocator, kernel cache and queue shared by everything that uses the GPU.

pub fn memory(&self) -> MemoryStats

Memory use and limits of this device’s allocator.

pub fn set_memory_limit(&self, bytes: usize) -> usize

Sets the memory limit (allocations beyond it fail) and returns the previous one.

pub fn set_cache_limit(&self, bytes: usize) -> usize

Sets the cache limit, trimming the cache to it, and returns the previous one.

pub fn set_wired_limit(&self, bytes: usize) -> Result<usize>

Sets the wired limit and returns the previous one (MLX’s set_wired_limit; 0 by default). Buffers, mapped files included, are kept resident up to this many bytes while GPU work runs, instead of being made resident per command buffer, which can page memory in again under pressure. Lowering it unwires buffers until the wired set fits. A limit above the recommended working set is an error. Without residency sets (before macOS 15, or on GPUs before Metal 3) the limit is recorded but nothing is wired.

pub fn can_wire(&self) -> bool

Whether buffers can be wired on this system (residency sets: macOS 15 and a Metal 3 GPU).

pub fn clear_cache(&self)

Releases every cached buffer.

pub fn in_flight(&self) -> usize

Command buffers committed on this device that have not completed yet.

pub fn wait_for_capacity(&self, max: usize)

Blocks until fewer than max command buffers are in flight (back-pressure for callers that submit without waiting).

pub fn reset_peak(&self)

Resets the peak to the current active memory.

pub fn info(&self) -> &DeviceInfo

What this GPU is and can do.

pub fn pipeline(&self, name: &str) -> Result<Pipeline>

The compute pipeline for the kernel name from nuvec’s kernel library, compiled on first use and cached.

pub fn pipeline_with( &self, name: &str, constants: &[(usize, bool)], ) -> Result<Pipeline>

The pipeline for kernel name specialised with boolean function constants (index, value), compiled on first use and cached per name and constants.

pub fn pipeline_with_constants( &self, name: &str, constants: &[(usize, Constant)], ) -> Result<Pipeline>

The pipeline for kernel name specialised with boolean or integer function constants (index, value), compiled on first use and cached per name and constants.

pub fn pipeline_from_source( &self, name: &str, source: impl FnOnce() -> String, ) -> Result<Pipeline>

The pipeline for kernel name from Metal source that source generates, compiled at runtime on first use and cached by name (so a name must always mean the same source). The source may include nuvec’s headers (#include "common.h"); it is compiled with IEEE-conformant math, as nuvec’s own kernels are.

Trait Implementations

impl Clone for Device

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Device

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.