Struct MlxArray 

pub struct MlxArray { /* private fields */ }

Owned MLX array handle released exactly once through the official C API.

Implementations

impl MlxArray

pub fn evaluate_after( &self, dependencies: &MlxArrayVector, ) -> Result<MlxArrayVector, MlxCError>

Schedules this array’s evaluation after the dependencies and returns the evaluated handle, matching MLX-C mlx_depends.

Errors

Returns the captured MLX-C description when scheduling fails.

impl MlxArray

pub fn load_from_file(path: &str, stream: &MlxStream) -> Result<Self, MlxCError>

Loads one array from a file through MLX-C mlx_load.

Errors

Returns the captured MLX-C description when loading fails.

pub fn save_to_file(&self, path: &str) -> Result<(), MlxCError>

Saves this array to a file through MLX-C mlx_save.

Errors

Returns the captured MLX-C description when saving fails.

impl MlxArray

pub fn all_gather( &self, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Gathers every rank’s copy of the array in the group.

Errors

Returns the captured MLX-C description when the collective fails.

pub fn all_max( &self, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Reduces the array across the group with a maximum.

Errors

Returns the captured MLX-C description when the collective fails.

pub fn all_min( &self, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Reduces the array across the group with a minimum.

Errors

Returns the captured MLX-C description when the collective fails.

pub fn all_sum( &self, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Reduces the array across the group with a sum.

Errors

Returns the captured MLX-C description when the collective fails.

pub fn sum_scatter( &self, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Scatters the array across the group with a sum.

Errors

Returns the captured MLX-C description when the collective fails.

pub fn send_to_rank( &self, destination: i32, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Sends this array to the destination rank.

Errors

Returns the captured MLX-C description when the send fails.

pub fn receive_from_rank( shape: &[i32], dtype: MlxDtype, source: i32, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Receives an array of the given shape from the source rank.

Errors

Returns the captured MLX-C description when the receive fails.

pub fn receive_like( &self, source: i32, group: &MlxDistributedGroup, stream: &MlxStream, ) -> Result<Self, MlxCError>

Receives an array matching this array’s shape from the source rank.

Errors

Returns the captured MLX-C description when the receive fails.

impl MlxArray

pub fn from_f32(values: &[f32], shape: &[i32]) -> Result<Self, MlxCError>

Creates a float32 array from host values, the way compiled-graph builders embed scalar constants (the softplus graph’s ln 2, the verification window’s attention-mask boundary values).

pub fn from_i32(values: &[i32], shape: &[i32]) -> Result<Self, MlxCError>

pub fn from_u32(values: &[u32], shape: &[i32]) -> Result<Self, MlxCError>

pub fn empty() -> Self

pub fn is_empty(&self) -> bool

pub const fn raw(&self) -> mlx_array

pub const fn empty_raw() -> mlx_array

The official absent-optional-handle placeholder for raw MLX calls.

Compiled-graph builders outside this crate mirror the runtime’s own operations and need the same empty convention for absent freqs, sinks, and global_scale handles; the placeholder owns nothing and is always valid to pass by value.

pub fn raw_mut(&mut self) -> *mut mlx_array

pub fn require_populated( &self, operation: &'static str, ) -> Result<(), MlxCError>

Validates that a returned handle is populated, translating a parked payload-closure failure or the captured MLX-C description into a typed failure.

This is a pure translation: embedding-specific error classification (for example an active memory ceiling) is embedding policy and happens when the consumer converts this error at its boundary.

pub fn shape(&self) -> Vec<i32>

Returns the dimensions of this live array.

pub fn dtype(&self) -> MlxDtype

Returns the array’s element type.

pub fn element_count(&self) -> usize

Returns the number of logical elements.

pub fn byte_count(&self) -> usize

Returns the logical tensor payload size in bytes.

pub fn evaluate(&self) -> Result<(), MlxCError>

Materializes this lazy array and reports runtime failures without exit.

pub fn to_vec_f32(&self) -> Result<Vec<f32>, MlxCError>

Evaluates and copies a contiguous float32 array into Rust-owned memory.

MLX keeps a slice of an evaluated parent as a strided view over the parent’s buffer, and the raw data pointer ignores those strides, so this readout is only valid for contiguous arrays. Read a strided view through MlxRuntime::array_to_vec_f32, whose flat reshape forces one contiguous materialization.

pub fn to_vec_u32(&self) -> Result<Vec<u32>, MlxCError>

pub fn to_vec_u8(&self) -> Result<Vec<u8>, MlxCError>

Evaluates and copies a uint8 array into Rust-owned memory.

pub fn copy_evaluated_u8_values(&self) -> Result<Vec<u8>, MlxCError>

Copies an already evaluated contiguous uint8 array in one host transfer.

pub fn copy_evaluated_u32_values(&self) -> Result<Vec<u32>, MlxCError>

Copies an already evaluated uint32 array into Rust-owned memory.

Callers must evaluate the array first. This split exists so performance attribution can distinguish the synchronization wait from the small host copy.

pub fn item_u32(&self) -> Result<u32, MlxCError>

Evaluates a scalar array and copies its value as an unsigned token ID.

pub fn retain(&self) -> Result<Self, MlxCError>

Creates a shared reference to the same underlying MLX data.

MLX uses reference counting, so this is cheap and does not copy the tensor data. The returned array shares the same lazy graph and evaluated buffers as the source.

impl MlxArray

pub fn from_bool(value: bool) -> Self

Creates a boolean scalar array.

pub fn from_scalar_i32(value: i32) -> Self

Creates an integer scalar array.

pub fn from_scalar_f32(value: f32) -> Self

Creates a float32 scalar array.

pub fn from_scalar_f64(value: f64) -> Self

Creates a float64 scalar array.

pub fn from_scalar_complex(real: f32, imag: f32) -> Self

Creates a complex scalar array from real and imaginary parts.

pub unsafe fn from_managed_buffer( buffer: Vec<u8>, shape: &[i32], dtype: MlxDtype, ) -> Result<Self, MlxCError>

Creates an array that borrows host memory without copying.

Safety

The buffer must stay valid and unmodified until the destructor runs, its contents must match dtype’s element layout, and its element count must match the shape product.

pub fn set_bool(&mut self, value: bool) -> Result<(), MlxCError>

Replaces this handle’s value with a boolean scalar.

pub fn set_i32(&mut self, value: i32) -> Result<(), MlxCError>

Replaces this handle’s value with an integer scalar.

pub fn set_f32(&mut self, value: f32) -> Result<(), MlxCError>

Replaces this handle’s value with a float32 scalar.

pub fn set_f64(&mut self, value: f64) -> Result<(), MlxCError>

Replaces this handle’s value with a float64 scalar.

pub fn set_complex(&mut self, real: f32, imag: f32) -> Result<(), MlxCError>

Replaces this handle’s value with a complex scalar.

pub fn item_size(&self) -> usize

The per-element byte size of the array’s dtype.

pub fn strides(&self) -> Vec<usize>

The element strides in elements per dimension.

pub fn dimension(&self, axis: i32) -> i32

The size of one dimension.

pub fn byte_size_of_dtype(dtype: MlxDtype) -> usize

The dtype’s element byte size.

pub fn item_bool(&self) -> Result<bool, MlxCError>

Copies the boolean scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_u8(&self) -> Result<u8, MlxCError>

Copies the uint8 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_u16(&self) -> Result<u16, MlxCError>

Copies the uint16 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_u64(&self) -> Result<u64, MlxCError>

Copies the uint64 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_i8(&self) -> Result<i8, MlxCError>

Copies the int8 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_i16(&self) -> Result<i16, MlxCError>

Copies the int16 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_i32(&self) -> Result<i32, MlxCError>

Copies the int32 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_i64(&self) -> Result<i64, MlxCError>

Copies the int64 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_f64(&self) -> Result<f64, MlxCError>

Copies the float64 scalar value.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_complex(&self) -> Result<(f32, f32), MlxCError>

Copies the complex scalar value as real and imaginary parts.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_f16_bits(&self) -> Result<u16, MlxCError>

Copies the float16 scalar value as raw bits.

Only on 64-bit ARM: the vendored mlx/c/half.h declares the float16 entry points under defined(__ARM_FEATURE_FP16_SCALAR_ARITHMETIC) || defined(__aarch64__), so the bridge mirrors that availability.

Errors

Returns the captured MLX-C description when the read fails.

pub fn item_bf16_bits(&self) -> Result<u16, MlxCError>

Copies the bfloat16 scalar value as raw bits.

Only on 64-bit ARM, mirroring the __bf16 guard in the vendored mlx/c/half.h.

Errors

Returns the captured MLX-C description when the read fails.

pub fn to_vec_bool(&self) -> Result<Vec<bool>, MlxCError>

Copies the evaluated boolean storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_u16(&self) -> Result<Vec<u16>, MlxCError>

Copies the evaluated uint16 storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_u64(&self) -> Result<Vec<u64>, MlxCError>

Copies the evaluated uint64 storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_i8(&self) -> Result<Vec<i8>, MlxCError>

Copies the evaluated int8 storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_i16(&self) -> Result<Vec<i16>, MlxCError>

Copies the evaluated int16 storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_i32(&self) -> Result<Vec<i32>, MlxCError>

Copies the evaluated int32 storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_i64(&self) -> Result<Vec<i64>, MlxCError>

Copies the evaluated int64 storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_f64(&self) -> Result<Vec<f64>, MlxCError>

Copies the evaluated float64 storage into Rust memory.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_f16_bits(&self) -> Result<Vec<u16>, MlxCError>

Copies the evaluated float16 storage into Rust memory as raw bits.

Only on 64-bit ARM, mirroring the float16 guard in the vendored mlx/c/half.h.

Errors

Returns the captured MLX-C description when the copy fails.

pub fn to_vec_bf16_bits(&self) -> Result<Vec<u16>, MlxCError>

Copies the evaluated bfloat16 storage into Rust memory as raw bits.

Only on 64-bit ARM, mirroring the bfloat16 guard in the vendored mlx/c/half.h.

Errors

Returns the captured MLX-C description when the copy fails.

Trait Implementations

impl Debug for MlxArray

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

Formats the value using the given formatter.

impl Drop for MlxArray

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.