ExTorch.Tensor.Blob (extorch v0.2.0)

Copy Markdown

Zero-copy tensor exchange between ExTorch and other tensor frameworks.

This module provides functions for sharing tensor memory across framework boundaries without copying data. It works by exchanging raw memory pointers between libraries that share the same process address space (e.g., ExTorch and Torchx/Nx, both backed by libtorch).

Safety

Memory lifetime is the caller's responsibility. When you create a tensor via from_blob/2, the source memory must remain valid for the lifetime of the returned tensor. The %ExTorch.Tensor.Blob{} struct returned by to_blob/1 holds a reference to the source tensor, preventing it from being garbage collected.

Example: ExTorch → Nx (via Torchx)

blob = ExTorch.Tensor.Blob.to_blob(extorch_tensor)
# Pass blob.ptr, blob.shape, blob.strides, blob.dtype to Torchx

Example: Nx (via Torchx) → ExTorch

view = ExTorch.Tensor.Blob.from_blob(
  %{ptr: torchx_data_ptr, shape: {3, 4}, dtype: :float32},
  owner: nx_tensor  # prevents GC of source
)
view.tensor  # the ExTorch tensor (shares memory with nx_tensor)

Summary

Types

t()
view()

A tensor view backed by foreign memory. Holds a reference to both the tensor and the memory owner, preventing the owner from being GC'd.

Functions

from_blob(blob_info, opts \\ [])

Create an ExTorch tensor from a raw memory pointer (zero-copy).

to_blob(tensor)

Extract raw memory information from an ExTorch tensor.

Types

t()

@type t() :: %ExTorch.Tensor.Blob{
  device: ExTorch.Device.device(),
  dtype: ExTorch.DType.dtype(),
  element_size: integer(),
  owner: ExTorch.Tensor.t(),
  ptr: integer(),
  shape: tuple(),
  strides: [integer()]
}

view()

@type view() :: %ExTorch.Tensor.BlobView{owner: term(), tensor: ExTorch.Tensor.t()}

A tensor view backed by foreign memory. Holds a reference to both the tensor and the memory owner, preventing the owner from being GC'd.

Functions

from_blob(blob_info, opts \\ [])

@spec from_blob(
  map(),
  keyword()
) :: view() | ExTorch.Tensor.t()

Create an ExTorch tensor from a raw memory pointer (zero-copy).

The returned tensor shares the memory at the given pointer. The caller must ensure the source memory outlives the returned tensor.

When :owner is provided, returns an %ExTorch.Tensor.BlobView{} that holds references to both the tensor and the owner, preventing the owner from being garbage collected while the view is alive.

Arguments

  • blob_info - A map, %Blob{}, or struct with keys: :ptr, :shape, :dtype. Optional keys: :strides, :device.
  • opts - Keyword options:
    • :owner - Any term to keep alive alongside the tensor (e.g., the source Nx tensor or Torchx reference).

Returns

An %ExTorch.Tensor.BlobView{} (when :owner is given) or %ExTorch.Tensor{} (without :owner -- caller assumes lifetime responsibility).

to_blob(tensor)

@spec to_blob(ExTorch.Tensor.t()) :: t()

Extract raw memory information from an ExTorch tensor.

Returns a %ExTorch.Tensor.Blob{} struct containing the pointer and metadata. The struct holds a reference to the source tensor, keeping it alive.

Arguments

  • tensor - The source %ExTorch.Tensor{}.

Returns

A %ExTorch.Tensor.Blob{} with fields:

  • ptr - Raw memory address (integer). Valid for CPU and CUDA pointers.
  • shape - Tensor shape as a tuple.
  • strides - Stride per dimension as a list of integers.
  • dtype - Element data type.
  • device - Device the memory lives on.
  • element_size - Size of each element in bytes.
  • owner - Reference to the source tensor (prevents GC).