Enum TensorMemory 

#[non_exhaustive]
#[repr(u32)]
pub enum TensorMemory {
    Mem = 0,
    Shm = 1,
    DmaBuf = 2,
    IoSurface = 3,
    Pbo = 4,
    Cuda = 5,
}

Which memory backend a tensor is (or should be) allocated from.

Pass Some(..) to a constructor to pin the backend, or None to auto-select. Auto-selection differs by constructor: Tensor::new tries DmaBuf → Mem, while the image constructors try DmaBuf → Mem and skip Shm. EDGEFIRST_TENSOR_FORCE_MEM=1 short-circuits either chain to Mem, which is how tests run on hosts without DMA-heap permissions.

A pinned request has no fallback: if the backend cannot serve it, the constructor fails rather than quietly giving you something slower. TensorTrait::memory reports what a tensor actually ended up with.

Every variant exists on every platform

This is a namespace of codes, not a list of what this build can allocate – TensorMemory::is_available answers the latter, at runtime. Shm used to be #[cfg(unix)], which shifted every variant declared after it on a non-unix build and made the numbering a compile-time detail of the host. It also made a cross-platform recording unreadable: a blob captured on Linux carries "dmabuf", and a macOS consumer has to be able to NAME that backing in order to report “cannot materialise here” instead of failing with an unrecognised code.

#[non_exhaustive]

Match this with a wildcard arm. The variant list is expected to keep growing – IoSurface and Cuda were added here, Windows backings and a real CUDA device backing are named as coming – and this attribute is what keeps a closed-source consumer’s match memory { .. } compiling across those additions. It protects DOWNSTREAM, not this crate: inside edgefirst-tensor the matches stay exhaustive and compile-enforced. Same rule as DType, Compression and PixelFormat, which TensorMemory was the lone exception to.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Mem = 0

Regular system memory allocation. Available everywhere; the floor every auto-selection chain ends on.

Shm = 1

POSIX Shared Memory allocation. Suitable for inter-process communication, but not for hardware acceleration. Only allocatable on unix; nameable everywhere.

DmaBuf = 2

Platform-native zero-copy GPU buffer.

On Linux this is a DMA-BUF (DmaTensor in crates/tensor/src/dma.rs) allocated via the DRM/dma-heap subsystem. On macOS/iOS it is currently also this variant that yields an IOSurface, and on Android an AHardwareBuffer: they share the TensorStorage::Dma slot at the trait level, and the public C API discriminant (HAL_TENSOR_MEMORY_DMA = 1) covers all three with no ABI break. IoSurface below is the code for naming that backing specifically; no backend reports it yet.

Allows hardware-accelerated paths (OpenGL backend on Linux via EGL_EXT_image_dma_buf_import; macOS via EGL_ANGLE_iosurface_client_buffer). CPU access via map() incurs cache-coherency overhead on Linux DMA-BUF and is similar in cost on IOSurface; SHM/Mem are cheaper for CPU-only workloads.

On Windows it is an ID3D11Texture2D on the process D3D11 device (crates/tensor/src/d3d11/), allocated only through Tensor::image; CPU access goes through a staging copy. The first such allocation creates the process device, so a host supplying its own device must call d3d11::use_external_device before it – and before crate::is_gpu_buffer_available, which creates the device too.

IoSurface = 3

Apple IOSurface, named specifically rather than through the portable DmaBuf spelling.

Defined as a code so a descriptor or recording that names an IOSurface is parseable on every platform. No backend produces or accepts it yet – macOS/iOS allocate and report DmaBuf. Pinning a request to it fails with NotImplemented.

Pbo = 4

OpenGL Pixel Buffer Object memory. Created by ImageProcessor when DMA-buf is unavailable but OpenGL is present – never by Tensor::new, which has no GL context to create it in.

Cuda = 5

CUDA device memory: a device pointer, not host-addressable.

Defined as a code for the same reason as IoSurface. No backend produces or accepts it yet; pinning a request to it fails with NotImplemented.

Implementations

impl TensorMemory

pub const fn code(self) -> u32

The shared code for this variant. Identical on every surface.

const, deliberately: a downstream binding that cannot write Variant = OtherEnum::Variant.code() in a #[pyclass] discriminant position (PyO3 requires a literal there) can still pin that literal to this value with a const _: () = assert!(...) – a build-time check instead of a hand-synced comment. See PyTensorMemory/PyPixelFormat in crates/python-common/src/tensor.rs for the consumer.

pub fn from_code(code: u32) -> Option<Self>

Reject an unknown code rather than guessing at one.

pub fn as_str(self) -> &'static str

The wire string form – stable, unlike Debug.

pub fn from_str_code(s: &str) -> Option<Self>

Reject an unknown string rather than guessing at one.

pub fn all() -> &'static [Self]

Every variant, for exhaustive cross-surface tests.

impl TensorMemory

pub fn is_available(self) -> bool

Whether this backing can actually be allocated in this process, now.

A runtime question, not a compile-time one, which is why it is a method on the vocabulary rather than a cfg on the variant: DmaBuf needs /dev/dma_heap to exist and this process to have permission on it (a container, a user outside the video/render groups, and a stock desktop give three different answers on the same kernel), and Shm needs a writable /dev/shm. Each probe allocates once and caches.

Reports what can be allocated, which is not the same as what can be named: every variant is nameable on every platform (that is the point of the vocabulary), and the ones this build cannot serve say so here rather than by being absent from the enum.

Three variants answer false unconditionally today, for reasons worth stating rather than hiding behind a probe that cannot fail:

• IoSurface – no backend produces or accepts it yet; macOS/iOS serve IOSurface under the DmaBuf spelling, so DmaBuf is the variant that answers true there.
• Pbo – PBO tensors are created by ImageProcessor::create_image with a GL context current, never by Tensor::new. This crate holds no GL context and cannot see one; ask the image crate whether a GL backend is live.
• Cuda – there is no CUDA backing in this crate at all. Probing for libcuda would answer true on a Jetson while every allocation still failed, which is worse than answering false.

One variant answers true for a narrower constructor than the rest: on Windows DmaBuf is an ID3D11Texture2D, which is image-formatted, so true there means Tensor::image can serve it and Tensor::new with Some(DmaBuf) still answers NotImplemented. is_gpu_buffer_available, which this forwards to, states the same split.

Trait Implementations

impl Clone for TensorMemory

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for TensorMemory

impl Debug for TensorMemory

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

Formats the value using the given formatter.

impl Eq for TensorMemory

impl From<TensorMemory> for String

fn from(memory: TensorMemory) -> Self

The wire string, via TensorMemory::as_str – one spelling, not a second one maintained alongside it.

DmaBuf renders as "dmabuf", not the "dma" this impl used to emit. TryFrom<&str> still accepts "dma" so anything that persisted the old spelling keeps parsing; the benchmark result keys in .github/scripts spell it "dma" but build that string themselves and never went through this impl.

impl Hash for TensorMemory

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for TensorMemory

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for TensorMemory

impl TryFrom<&str> for TensorMemory

fn try_from(s: &str) -> Result<Self>

Parses TensorMemory::as_str’s spelling, plus the legacy "dma" alias for DmaBuf.

type Error = Error

The type returned in the event of a conversion error.