ClikaRT::io::TensorsContainer

class

Header: ClikaRT/io/tensors_container.h

A lazily-materializing view of a checkpoint's tensors. Move-only: the container caches each materialized tensor so repeated gets share one storage, and that cache must have a single owner (a sub-container from subset shares the cache of the entries it carries). A container from io::peek_gguf holds a header only: the queries (names, entry, size, total_bytes, entry_bytes, contains) answer, and every call that reads tensor data fails with Status::InvalidArgument.

Nested types

Name	Description
Entry	One parsed (never materialized) checkpoint entry, the header-only metadata a placement or config probe reads with no payload IO.

Member functions

TensorsContainer()

TensorsContainer()

An empty container (no entries).

Declared in ClikaRT/io/tensors_container.h, line 95

TensorsContainer(TensorsContainer)

TensorsContainer(TensorsContainer&& other) noexcept

Move: transfers the container handle.

Declared in ClikaRT/io/tensors_container.h, line 98

operator=(TensorsContainer)

TensorsContainer& operator=(TensorsContainer&& other) noexcept

Move-assign: transfers the container handle.

Declared in ClikaRT/io/tensors_container.h, line 100

TensorsContainer(TensorsContainer)

TensorsContainer(const TensorsContainer&) =delete

Declared in ClikaRT/io/tensors_container.h, line 101

operator=(TensorsContainer)

TensorsContainer& operator=(const TensorsContainer&) =delete

Declared in ClikaRT/io/tensors_container.h, line 102

~TensorsContainer()

~TensorsContainer()

Releases the container (open file mappings close with the last user).

Declared in ClikaRT/io/tensors_container.h, line 104

get()

Tensor get(std::string_view name)

Materialize (or return the cached) tensor under name. Raises ClikaRT::Error for an unknown name or a failed materialization.

Declared in ClikaRT/io/tensors_container.h, line 109

load_all()

NamedTensors load_all()

Materialize EVERY entry into an eager NamedTensors map.

Declared in ClikaRT/io/tensors_container.h, line 113

prefetch()

void prefetch(ClikaRT::Span<const std::string> names, StreamOrDevice where = {})

Warm entries ahead of use: read-ahead on their file ranges; an evicted materialized tensor restores now, asynchronously on where when set (a stream the restore rides, program-ordered with the caller's work there; a device picks its default stream), else on the runtime's dedicated per-device residency stream. Unknown names raise ClikaRT::Error. names is read during the call, not retained.

Declared in ClikaRT/io/tensors_container.h, line 122

load_into()

void load_into(
    std::string_view name,
    Tensor& dst,
    StreamOrDevice where = {}
)

Write name's payload bytes INTO the caller's dst buffer; no allocation, no file-backing stamped: the buffer stays the caller's (the persistent double-buffer shape a streaming loop overwrites each step). dst must match the entry's shape and dtype; a cross-device dst receives the bytes through the transfer path, riding where (unset ⇒ dst's own stream). dst ends carrying the entry's quantization scheme, the one get returns with it, and a plain entry leaves dst with none, whatever it carried before. Raises ClikaRT::Error for an unknown name or a mismatched destination.

Declared in ClikaRT/io/tensors_container.h, line 134

evict()

void evict(std::string_view name)

Drop the container's cached handle for name; after an evict the bound consumer owns the storage alone, and a later get of the same name materializes FRESH storage (identity across an evict is not preserved). Residency follows the entry's placement and intent: a host-resident file-backed entry releases its memory back to the file (a consumer that bound it sees its next use restore transparently), and an entry loaded under the sticky disk-backed policy releases wherever it lives; a device-resident entry loaded WITHOUT the sticky policy keeps its device memory; the caller that bound it keeps the residency it paid to establish, and releasing device residency is that caller's own move (a module tree releases through to). A name that was never materialized is a no-op; an unknown name raises ClikaRT::Error. Requires that no caller still holds a raw data pointer into a released entry.

Declared in ClikaRT/io/tensors_container.h, line 151

evict_all()

void evict_all()

Evict every materialized tensor under evict's own per-entry rule (first failure aborts and raises).

Declared in ClikaRT/io/tensors_container.h, line 156

release()

void release(std::string_view name)

Drop the container's cached handle for name (the entry stays; a later get re-materializes). No-op when nothing is cached.

Declared in ClikaRT/io/tensors_container.h, line 160

contains()

bool contains(std::string_view name) const

True if the checkpoint has an entry under name.

Declared in ClikaRT/io/tensors_container.h, line 163

size()

std::size_t size() const

Number of entries.

Declared in ClikaRT/io/tensors_container.h, line 165

total_bytes()

std::size_t total_bytes() const

Sum of every entry's on-disk payload bytes, the checkpoint's total footprint, known without materializing anything.

Declared in ClikaRT/io/tensors_container.h, line 168

entry_bytes()

std::uint64_t entry_bytes(std::string_view name) const

One entry's on-disk payload bytes (0 for an unknown name), the per-tensor feed a placement scheduler sums into per-unit (e.g. per-layer) budgets against a LoadPlan's resident_byte_budget. A composed (adapted) entry reports the sum of its parts' bytes.

Declared in ClikaRT/io/tensors_container.h, line 173

names()

std::vector<std::string> names() const

All entry names, sorted.

Declared in ClikaRT/io/tensors_container.h, line 175

entry()

std::optional<Entry> entry(std::string_view name) const

The parsed metadata behind name: introspection with NO materialization and no payload IO. std::nullopt for an unknown name AND for a composed (adapted) name: a composed value is derived, so it has no single parsed entry; probe its existence via contains/names and its cost via entry_bytes.

Declared in ClikaRT/io/tensors_container.h, line 201

subset(SubsetSpec)

TensorsContainer subset(const SubsetSpec& spec)

The sub-container over the entries spec selects, served under the names spec produces (SubsetSpec): a block built from its config loads its weights by its own names through nn::Module::load_state_dict(container.subset("model.layers.3.")), and the strict verdict there accounts against the sub-container's names alone. Header-only work: nothing is read or copied, the sub-container keeps this container's load policy, and it is a container like any other (get, prefetch, evict, release, load_into, a further subset). An empty selection is an empty sub-container. Raises ClikaRT::Error naming the entry when two entries produce one name, a produced name is empty, the pattern does not compile, or strip is asked of a pattern with no capture group.

Declared in ClikaRT/io/tensors_container.h, line 217

subset(string_view, bool, bool)

TensorsContainer subset(
    std::string_view prefix,
    bool strip = true,
    bool return_clone = false
)

The prefix form of subset: the entries whose names start with prefix, served with it stripped (strip), moved out of this container unless return_clone.

Declared in ClikaRT/io/tensors_container.h, line 221