Runtime tensors#
The unit of data between a host and anira at run time is anira_tensor (anira/abi/tensor.h,
anira::Tensor in C++): a descriptor of memory, never the memory itself, 216 bytes,
trivially copyable and laid out the same on wasm32, LP64 and LLP64.
#include <anira/abi/tensor.h>
float samples[2 * 512];
const int64_t shape[2] = { 2, 512 }; /* [channels, samples] */
anira_tensor t; /* caller memory: the stack is fine */
anira_tensor_init_host(&t, samples, ANIRA_DTYPE_F32, 2, shape);
float* first = anira_tensor_data_f32(&t); /* NULL for a device or a non-float tensor */
size_t count = anira_tensor_num_elements(&t); /* 1024 */
size_t frames = anira_tensor_extent(&t, 1); /* 512; 0 for an axis at or above ndim */
float left[512], right[512];
float* channels[2] = { left, right }; /* an audio host's channel pointers */
anira_tensor planar;
anira_tensor_init_host_planar(&planar, channels, 2, ANIRA_DTYPE_F32, 2, shape); /* no cast */
float* second = anira_tensor_plane(&planar, 1, ANIRA_DTYPE_F32); /* right */
anira_error err = ANIRA_ERROR_INIT;
anira_tensor from_numpy; /* managed: a DLManagedTensorVersioned* */
if (ANIRA_FAILED(anira_tensor_init_dlpack(&from_numpy, managed, &err))) { return fail(&err); }
/* ... off the driver thread, once no longer needed: */
if (from_numpy.release != NULL) { from_numpy.release(&from_numpy); } /* the producer's deleter, once */
The record: domain (where the bytes live), dtype, ndim, flags, shape and strides
(eight int64_t each; strides in elements, all-zero meaning packed row-major), byte_offset, the
memory handle (a 24-byte union with one arm per domain: host, cuda, gl, vk,
opaque, mtl, iosurface, wgpu, dmabuf, ahb, d3d12, planes, and
raw[3]), the producer’s manager_ctx and release, and acquire, the fence after which
the data is valid (an anira_sync_token; ANIRA_SYNC_NONE: already visible). The three records
are Tier 1: no struct_size, the ABI major is their version, their layout is committed in
abi/layout-<major>.txt and mirrored in web/src/abi/layout.ts; anira_sizeof(ANIRA_STRUCT_TENSOR)
answers an allocator that cannot see the header (0 for an id this build does not know). The Hard and
Static entries take host tensors; only
host memory is read in this pre-release.
Factories and reads#
anira_tensor_init_hostand_init_pinneddescribe host memory;_init_cuda,_init_gl_buffer,_init_vulkan,_init_opaque_fd,_init_wgpu_bufferand_init_dmabufdevice memory, each ending indtype, ndim, shape. They zero all 216 bytes and write the domain, the dtype, the rank, the extents, their handle arm and the fence: a borrowed, packed tensor until the producer sets more. A NULL data pointer is accepted (a field fill never looks at the memory; the Hard entries refuse NULL memory per call). They are[thread-safe],[callback-safe]andANIRA_NONBLOCKINGfield fills, legal on a render thread and in a processor callback.They return nothing: a dtype of 0, a rank above
ANIRA_MAX_RANK, a NULL shape with a rank above 0 or a negative extent leave the record all-zero, which reads as dtype 0. Every argument is read before the record is zeroed, soanira_tensor_init_host(&t, p, t.dtype, t.ndim, t.shape)re-points a tensor. The previous content is overwritten, never released: reset an owningacquireand call areleasefirst.A NULL event, sync or fence, a timeline semaphore of 0 and a negative
sync_fdleaveANIRA_SYNC_NONE: anira never fabricates a fence (a WebGPU producer whose work is queued passesANIRA_SYNC_QUEUE_ORDERED). A token passed by pointer is copied intoacquire, which is the hand-off: the caller does not reset its source, unless the call was refused, when the token was not copied and stays the caller’s. The six device factories are field fills only in this pre-release: no adapter consumes their arms.anira_tensor_init_dlpack(&t, dl_managed_tensor_versioned, &err)is the one factory that can fail with a message, the one[main-thread]one. It takes a DLPack 1.xDLManagedTensorVersioned*asvoid*, maps the CPU toANIRA_DOMAIN_HOSTand CUDA host memory toANIRA_DOMAIN_HOST_PINNED, takes theDLDataTypeas theanira_dtypeit already is (codes 0 to 6), copies shape, strides (NULL: packed), pointer and offset, and maps the read-only flag toANIRA_TENSOR_READ_ONLY. Another device, a code above 6, a major other than 1, and all-zero strides over more than one element areANIRA_ERROR_NOT_SUPPORTED; a rank outside 0 to 8, a NULL shape, a negative extent and a dtype of 0 bits or lanesANIRA_ERROR_INVALID_ARGUMENT. A refused call leaves the record untouched and never calls the deleter; a NULL deleter gives a borrowed tensor (releasestays NULL).anira_tensor_data_f32(&t)returns the first element (handle.host.ptrplusbyte_offset) of a host or pinned float32 tensor, and NULL for every other domain or dtype and for a NULL base pointer;anira_tensor_data(&t, dtype)is the same read for any element type, NULL unlessdtypeis the tensor’s own. Neither looks at the strides.anira_tensor_num_elements(1 at rank 0, 0 with a zero extent and for the all-zero record) andanira_tensor_extentaresize_tand answer 0 for what is no count. These reads,anira_tensor_planeandanira_sizeofare the whole read surface,[thread-safe],[callback-safe]andANIRA_NONBLOCKING: legal in a processor callback.
Planar host memory. anira_tensor_init_host_planar(&t, planes, count, dtype, ndim, shape)
describes one pointer per channel without copying: axis 0 is the plane axis (a rank of 1 or more),
count must equal shape[0] (else, and at rank 0, the record is left all-zero),
ANIRA_TENSOR_PLANAR is set and handle.planes holds the pointer array, borrowed
like the memory. strides[0] is ignored; the strides from axis 1 and byte_offset apply inside
each plane. The array travels as const void*, so float** and const float* const* both
convert without a cast (under clang-tidy’s bugprone-multi-level-implicit-pointer-conversion,
write static_cast<const void*>(channels) or use the C++ spelling). OR ANIRA_TENSOR_READ_ONLY
into flags over read-only planes, and assign ANIRA_DOMAIN_HOST_PINNED over page-locked ones.
anira_tensor_plane(&t, i, dtype) reads one plane (NULL for a one-block tensor, a plane at or
above handle.planes.count, another domain or another dtype); the two data reads return NULL for
a planar tensor. An entry accepts a planar tensor only where its documentation says so (where it
copies a host block); every other consumer, and every domain but the two host ones, refuses the
flag with ANIRA_ERROR_NOT_SUPPORTED, and anira
never hands a planar tensor to a processor, an engine or JavaScript.
Ownership, release and sync tokens#
release == NULLmeans borrowed: the memory stays the caller’s and must stay valid until the call returns (Hard) or the ticket is terminal (Async). A non-NULLreleasefrees what the producer attached throughmanager_ctx; anira would call it exactly once per submitted copy, never on the driver thread (it may block and free), but no entry takes ownership in this pre-release, so the holder calls it once itself. A DLPack tensor’sreleasedisarms the record before it calls the deleter.
Warning
A DLPack deleter is not real-time safe (it frees memory; a Python producer’s takes the
interpreter lock): never call release on the driver thread. The disarming guards one record,
not its bitwise copies: release one copy only.
ANIRA_SYNC_SYNC_FILE_FDandANIRA_SYNC_OPAQUE_FD_SEMAPHOREown their file descriptor (u.fd, 0 or more; on Windows an NT handle above 0). Every hand-off is a transfer: never close an fd you handed to a tensor (anira_tensor_init_dmabuf’ssync_fdbelongs to the record from the call on, and stays yours when the call is refused).anira_sync_token_reset(&token)closes an owned fd and zeroes the token (kindANIRA_SYNC_NONE: a second reset closes nothing);anira_sync_token_dup(&token, &out)makes a token that outlives its source, a new close-on-exec descriptor for the two owning kinds and a plain copy of every other kind (ANIRA_ERROR_INVALID_ARGUMENTfor a NULL or aliasing argument or a closed fd,ANIRA_ERROR_OUT_OF_MEMORYout of descriptors;*outuntouched on failure). Both are[thread-safe, !audio-thread]. After a reset testkind, never the payload. Every other kind (a CUDA event, a Vulkan timeline semaphore, aGLsync, a Metal shared event, a D3D12 fence) is a non-owning handle. On WebAssembly no kind owns an object, anddupof an owning kind with an fd isANIRA_ERROR_NOT_SUPPORTED.
The draft folder and compiling the headers#
anira/abi/draft/tensor_platform.h declares the factories of the arms that have no measured edge
yet: anira_tensor_init_metal, _init_iosurface, _init_ahardwarebuffer and _init_d3d12,
field fills on every platform (shared_event and fence are tokens, copied like the WebGPU
fence; fence_fd follows the sync_fd rule). Their arms are frozen with anira_memory_handle; the factories are
outside the ABI promise (abi/symbols-draft.txt) until the platform is measured, and promotion
never renames them. <anira/anira.h> does not include the draft folder; <anira/anira_all.h>
does.
Every pointer of the three records sits in an ANIRA_PTR(T, name) slot, an anonymous union with a
uint64_t name_bits, 8 bytes on every target. So zero a record before filling it by hand (the
factories do), since on a 32-bit target a slot’s high half is otherwise undefined. MSVC at /W4
reports C4201 (nameless struct/union) for every slot: compile with /wd4201. The arms are unnamed
struct types with a member name (t.handle.cuda.device), valid ISO C++17 under -pedantic. The
layout is the natural alignment of wasm32, LP64, LLP64, 32-bit ARM and 32-bit MSVC; it does not hold
on the i386 System V ABI, which anira does not target.
In C++#
anira::Tensor and anira::SyncToken are these structs with names on them (a Tensor* is an
anira_tensor*): Tensor::from_host(data, dtype, shape) and from_pinned, from_cuda,
from_gl_buffer, from_vulkan, from_opaque_fd, from_wgpu_buffer, from_dmabuf are the
noexcept field fills; Tensor::from_host_planar<float>(planes, shape) and plane<T>(i) are
the typed planar spellings (the element type names the dtype, a const element sets
ANIRA_TENSOR_READ_ONLY); from_dlpack throws anira::Error; data_f32(), data(dtype),
num_elements() and extent(axis) are the reads, SyncToken::reset() and dup() the two
token calls. The draft factories have no C++ spelling: call anira_tensor_init_metal(&tensor, ...)
on a Tensor.