Struct MlxBuffer 

pub struct MlxBuffer { /* private fields */ }

A Metal GPU buffer annotated with element dtype and tensor shape.

On Apple Silicon the underlying memory is unified — contents_ptr() gives direct CPU access without any copy or transfer.

Thread Safety

MlxBuffer is Send + Sync because the inner metal::Buffer is.

Implementations

impl MlxBuffer

pub fn from_raw(inner: MetalBuffer, dtype: DType, shape: Vec<usize>) -> Self

Create a new MlxBuffer wrapping an already-allocated Metal buffer.

When to use

Use this to wrap Metal buffers obtained from external frameworks (e.g. candle’s MetalStorage::buffer()) for zero-copy interop on Apple Silicon unified memory. Both frameworks see the same physical memory.

Safety contract

The caller must ensure that inner remains valid for the lifetime of the returned MlxBuffer. If the buffer was obtained from another framework, the caller must ensure that framework does not deallocate the buffer while this MlxBuffer exists.

pub fn slice_view(&self, byte_offset: u64, n_elements: usize) -> Self

Create a zero-copy slice view of this buffer.

Returns a new MlxBuffer that shares the same underlying Metal buffer but starts at byte_offset bytes from the beginning and contains n_elements elements of type dtype. No data is copied.

When this view is bound to a kernel, the encoder passes the byte offset to Metal’s setBuffer:offset:atIndex:, so the kernel sees only the slice region.

Panics

Panics if byte_offset + n_elements * dtype.size_of() > self.inner.length().

pub fn dtype(&self) -> DType

Element data type.

pub fn shape(&self) -> &[usize]

Tensor shape (dimensions).

pub fn byte_len(&self) -> usize

Total byte length of the Metal buffer.

pub fn element_count(&self) -> usize

Number of elements (product of shape dimensions, or byte_len / dtype.size_of()).

pub fn contents_ptr(&self) -> *mut c_void

Raw pointer to the buffer contents (CPU-accessible on Apple Silicon).

Safety

The caller must ensure proper synchronization — do not read while a GPU command buffer that writes this buffer is in flight.

pub fn metal_buffer(&self) -> &MetalBuffer

Reference to the underlying metal::Buffer for passing to the encoder.

pub fn byte_offset(&self) -> u64

Byte offset into the underlying Metal buffer (zero for non-slice buffers).

When passing this buffer to a Metal kernel via setBuffer:offset:atIndex:, use this offset so the kernel sees only the intended sub-region.

pub fn as_slice<T: Pod>(&self) -> Result<&[T]>

View the buffer contents as a typed slice.

Returns an error if the buffer byte length is not an exact multiple of size_of::<T>().

Safety contract

The caller must ensure:

1. T matches the actual element type stored in the buffer.
2. No GPU command buffer that writes this buffer is currently in flight.

pub fn as_mut_slice<T: Pod>(&mut self) -> Result<&mut [T]>

View the buffer contents as a mutable typed slice.

Same safety contract as as_slice, plus: the caller must ensure exclusive access (no other references to this buffer’s memory exist).

Trait Implementations

impl Clone for MlxBuffer

fn clone(&self) -> Self

Increment the Metal buffer’s ARC retain count and wrap it in a new MlxBuffer. Both the original and the clone refer to the same underlying GPU allocation — no data is copied.

This is safe because metal::Buffer wraps an MTLBuffer Objective-C object whose lifetime is managed by ARC; Clone calls retain and drop calls release.

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

Performs copy-assignment from source.

impl Debug for MlxBuffer

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

Formats the value using the given formatter.