---
title: "ClikaRT::io::TensorsContainer"
sidebar_label: "TensorsContainer"
description: "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-conta…"
---

<!-- Generated by tools/doxygen2mdx from Doxygen XML. Do not edit. -->

<span class="api-kind api-kind--class">class</span>

**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 [`get`](./TensorsContainer.md#get)s share one storage, and that cache must have a single owner (a sub-container from [`subset`](./TensorsContainer.md#subset) shares the cache of the entries it carries). A container from [`io::peek_gguf`](./index.md#peek_gguf) holds a header only: the queries ([`names`](./TensorsContainer.md#names), [`entry`](./TensorsContainer.md#entry), [`size`](./TensorsContainer.md#size), [`total_bytes`](./TensorsContainer.md#total_bytes), [`entry_bytes`](./TensorsContainer.md#entry_bytes), [`contains`](./TensorsContainer.md#contains)) answer, and every call that reads tensor data fails with [`Status::InvalidArgument`](../../index.md#Status).

## Nested types

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

## Member functions

### TensorsContainer() {#TensorsContainer}

<div class="api-signature">

**`TensorsContainer`**()

</div>

An empty container (no entries).

<div class="api-declared">

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

</div>

### TensorsContainer(TensorsContainer) {#TensorsContainer-2}

<div class="api-signature">

**`TensorsContainer`**(`TensorsContainer&&` `other`) `noexcept`

</div>

Move: transfers the container handle.

<div class="api-declared">

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

</div>

### operator=(TensorsContainer) {#operator-assign}

<div class="api-signature">

[`TensorsContainer`](./TensorsContainer.md)`&` **`operator=`**([`TensorsContainer`](./TensorsContainer.md)`&&` `other`) `noexcept`

</div>

Move-assign: transfers the container handle.

<div class="api-declared">

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

</div>

### TensorsContainer(TensorsContainer) {#TensorsContainer-3}

<div class="api-signature">

**`TensorsContainer`**(`const TensorsContainer&`) `=delete`

</div>

<div class="api-declared">

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

</div>

### operator=(TensorsContainer) {#operator-assign-2}

<div class="api-signature">

[`TensorsContainer`](./TensorsContainer.md)`&` **`operator=`**(`const` [`TensorsContainer`](./TensorsContainer.md)`&`) `=delete`

</div>

<div class="api-declared">

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

</div>

### \~TensorsContainer() {#TensorsContainer-4}

<div class="api-signature">

**`~TensorsContainer`**()

</div>

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

<div class="api-declared">

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

</div>

### get() {#get}

<div class="api-signature">

[`Tensor`](../Tensor.md) **`get`**(`std::string_view` `name`)

</div>

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

<div class="api-declared">

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

</div>

### load\_all() {#load_all}

<div class="api-signature">

[`NamedTensors`](../NamedTensors.md) **`load_all`**()

</div>

Materialize EVERY entry into an eager [`NamedTensors`](../NamedTensors.md) map.

<div class="api-declared">

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

</div>

### prefetch() {#prefetch}

<div class="api-signature">

`void` **`prefetch`**([`ClikaRT::Span`](../Span.md)`<const std::string>` `names`, [`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`)

</div>

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`](../Error.md). [`names`](./TensorsContainer.md#names) is read during the call, not retained.

<div class="api-declared">

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

</div>

### load\_into() {#load_into}

<div class="api-signature">

`void` **`load_into`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `name`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`Tensor`](../Tensor.md)`&` `dst`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;[`StreamOrDevice`](../StreamOrDevice.md) `where` `=` `{}`<br />
)

</div>

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`](./TensorsContainer.md#get) returns with it, and a plain entry leaves `dst` with none, whatever it carried before. Raises [`ClikaRT::Error`](../Error.md) for an unknown name or a mismatched destination.

<div class="api-declared">

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

</div>

### evict() {#evict}

<div class="api-signature">

`void` **`evict`**(`std::string_view` `name`)

</div>

Drop the container's cached handle for `name`; after an evict the bound consumer owns the storage alone, and a later [`get`](./TensorsContainer.md#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`](../Error.md). Requires that no caller still holds a raw data pointer into a released entry.

<div class="api-declared">

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

</div>

### evict\_all() {#evict_all}

<div class="api-signature">

`void` **`evict_all`**()

</div>

Evict every materialized tensor under [`evict`](./TensorsContainer.md#evict)'s own per-entry rule (first failure aborts and raises).

<div class="api-declared">

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

</div>

### release() {#release}

<div class="api-signature">

`void` **`release`**(`std::string_view` `name`)

</div>

Drop the container's cached handle for `name` (the entry stays; a later [`get`](./TensorsContainer.md#get) re-materializes). No-op when nothing is cached.

<div class="api-declared">

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

</div>

### contains() {#contains}

<div class="api-signature">

`bool` **`contains`**(`std::string_view` `name`) `const`

</div>

True if the checkpoint has an entry under `name`.

<div class="api-declared">

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

</div>

### size() {#size}

<div class="api-signature">

`std::size_t` **`size`**() `const`

</div>

Number of entries.

<div class="api-declared">

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

</div>

### total\_bytes() {#total_bytes}

<div class="api-signature">

`std::size_t` **`total_bytes`**() `const`

</div>

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

<div class="api-declared">

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

</div>

### entry\_bytes() {#entry_bytes}

<div class="api-signature">

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

</div>

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`](./LoadPlan.md)'s `resident_byte_budget`. A composed (adapted) entry reports the sum of its parts' bytes.

<div class="api-declared">

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

</div>

### names() {#names}

<div class="api-signature">

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

</div>

All entry names, sorted.

<div class="api-declared">

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

</div>

### entry() {#entry}

<div class="api-signature">

`std::optional<`[`Entry`](./TensorsContainer.Entry.md)`>` **`entry`**(`std::string_view` `name`) `const`

</div>

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`](./TensorsContainer.md#contains)/[`names`](./TensorsContainer.md#names) and its cost via [`entry_bytes`](./TensorsContainer.md#entry_bytes).

<div class="api-declared">

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

</div>

### subset(SubsetSpec) {#subset}

<div class="api-signature">

[`TensorsContainer`](./TensorsContainer.md) **`subset`**(`const` [`SubsetSpec`](./SubsetSpec.md)`&` `spec`)

</div>

The sub-container over the entries [`spec`](../spec/index.md) selects, served under the names [`spec`](../spec/index.md) produces ([`SubsetSpec`](./SubsetSpec.md)): a block built from its config loads its weights by its own names through [`nn::Module::load_state_dict`](../nn/Module.md#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`](./TensorsContainer.md#get), [`prefetch`](./TensorsContainer.md#prefetch), [`evict`](./TensorsContainer.md#evict), [`release`](./TensorsContainer.md#release), [`load_into`](./TensorsContainer.md#load_into), a further [`subset`](./TensorsContainer.md#subset)). An empty selection is an empty sub-container. Raises [`ClikaRT::Error`](../Error.md) 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.

<div class="api-declared">

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

</div>

### subset(string\_view, bool, bool) {#subset-2}

<div class="api-signature">

[`TensorsContainer`](./TensorsContainer.md) **`subset`**(<br />
&nbsp;&nbsp;&nbsp;&nbsp;`std::string_view` `prefix`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`bool` `strip` `=` `true`,<br />
&nbsp;&nbsp;&nbsp;&nbsp;`bool` `return_clone` `=` `false`<br />
)

</div>

The prefix form of [`subset`](./TensorsContainer.md#subset): the entries whose names start with `prefix`, served with it stripped (`strip`), moved out of this container unless `return_clone`.

<div class="api-declared">

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

</div>