skainet-lang-core/sk.ainet.lang.tensor.storage/BufferHandle

BufferHandle

Ownership / residency mode of a tensor's backing memory.

Every TensorStorage holds a BufferHandle that describes how the runtime acquired the bytes and therefore what operations are legal:

Mode	Mutable?	Runtime owns memory?	Can outlive source?
Owned	yes	yes	yes
Borrowed	no*	no	no
Aliased	no	no (shared)	tied to parent
FileBacked	no	no (OS-managed)	tied to mapping
DeviceResident	varies	backend-managed	tied to device ctx

*Borrowed buffers expose the original array but callers must not mutate it unless they know the source permits mutation.

Inheritors

Types

Aliased

class Aliased(val parent: BufferHandle, val byteOffset: Long, val sizeInBytes: Long) : BufferHandle

A slice/view into another BufferHandle. Shares the parent's backing memory. Mutations (if the parent is mutable) are visible to both.

Borrowed

class Borrowed(val data: ByteArray, val offset: Int = 0, val sizeInBytes: Long = (data.size - offset).toLong(), val isMutable: Boolean = false) : BufferHandle

A reference to externally-owned memory (e.g. a caller-supplied array). The runtime must not free or resize it. Mutation is possible only if the source explicitly permits it.

DeviceResident

class DeviceResident(val deviceId: String, val backendHandle: Any, val sizeInBytes: Long, val isMutable: Boolean) : BufferHandle

Buffer managed by a compute backend (GPU, NPU, DSP, …). Access semantics depend on the backend.

FileBacked

class FileBacked(val path: String, val fileOffset: Long, val sizeInBytes: Long) : BufferHandle

Memory-mapped file region. Immutable from the runtime's perspective (the OS manages paging and eviction).

Owned

class Owned(val data: ByteArray, val offset: Int = 0, val sizeInBytes: Long = (data.size - offset).toLong()) : BufferHandle

Runtime-allocated copy. The runtime owns the underlying memory and is free to mutate or release it.

Properties

isMutable

abstract val isMutable: Boolean

Whether this handle permits writing into the buffer.

ownership

abstract val ownership: Ownership

Ownership classification for diagnostics.

sizeInBytes

abstract val sizeInBytes: Long

Total size in bytes of the accessible region.