---
title: "ClikaRT::device::MemoryStats"
sidebar_label: "MemoryStats"
description: "struct ClikaRT::device::MemoryStats"
---

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

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

**Header:** `ClikaRT/compute/memory_stats.h`

Per-device memory telemetry: the device's physical free/total plus the runtime memory pool's counters for that device. `memory_stats(device)` answers "where did the memory go" for exactly the device a load or a serve targets, the load-time companion of `is_backend_available()`; `release_cached_memory(device)` returns the pool's idle reserve to the driver or the OS; `reset_peak_memory_stats(device)` restarts the pool's high-water marks so one step's transient can be measured.

## Data members

### device\_free\_bytes {#device_free_bytes}

<div class="api-signature">

`std::uint64_t` **`device_free_bytes`** `= 0`

</div>

physical bytes currently free

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 41

</div>

### device\_total\_bytes {#device_total_bytes}

<div class="api-signature">

`std::uint64_t` **`device_total_bytes`** `= 0`

</div>

physical capacity

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 42

</div>

### device\_memory\_source {#device_memory_source}

<div class="api-signature">

[`MemorySource`](./index.md#MemorySource) **`device_memory_source`** `=` [`MemorySource::Unknown`](./index.md#MemorySource)

</div>

How the two physical figures above were obtained.

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 44

</div>

### active\_bytes {#active_bytes}

<div class="api-signature">

`std::uint64_t` **`active_bytes`** `= 0`

</div>

pool bytes currently handed out

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 46

</div>

### requested\_bytes {#requested_bytes}

<div class="api-signature">

`std::uint64_t` **`requested_bytes`** `= 0`

</div>

Bytes the live allocations asked for: [`active_bytes`](./MemoryStats.md#active_bytes) less the pool's carve slack (a free block at or above the pool's split ceiling serves a smaller request whole). The residency gauge: a second live copy of a weight doubles it, a bigger chunk does not move it.

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 51

</div>

### reserved\_bytes {#reserved_bytes}

<div class="api-signature">

`std::uint64_t` **`reserved_bytes`** `= 0`

</div>

pool bytes held from the driver (active + cached)

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 52

</div>

### cached\_bytes {#cached_bytes}

<div class="api-signature">

`std::uint64_t` **`cached_bytes`** `= 0`

</div>

idle pool bytes retained for reuse

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 53

</div>

### peak\_active\_bytes {#peak_active_bytes}

<div class="api-signature">

`std::uint64_t` **`peak_active_bytes`** `= 0`

</div>

high-water mark of active\_bytes

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 55

</div>

### peak\_reserved\_bytes {#peak_reserved_bytes}

<div class="api-signature">

`std::uint64_t` **`peak_reserved_bytes`** `= 0`

</div>

high-water mark of reserved\_bytes

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 56

</div>

### peak\_requested\_bytes {#peak_requested_bytes}

<div class="api-signature">

`std::uint64_t` **`peak_requested_bytes`** `= 0`

</div>

High-water mark of [`requested_bytes`](./MemoryStats.md#requested_bytes). Like [`requested_bytes`](./MemoryStats.md#requested_bytes), it counts what the live allocations asked for, so a larger block serving a request does not move it: the exact measure of the largest transient a step needed.

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 61

</div>

### num\_allocs {#num_allocs}

<div class="api-signature">

`std::uint64_t` **`num_allocs`** `= 0`

</div>

successful pool allocations

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 63

</div>

### num\_frees {#num_frees}

<div class="api-signature">

`std::uint64_t` **`num_frees`** `= 0`

</div>

pool frees

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 64

</div>

### num\_oom {#num_oom}

<div class="api-signature">

`std::uint64_t` **`num_oom`** `= 0`

</div>

pool out-of-memory events

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 65

</div>

### num\_inflight\_park\_waits {#num_inflight_park_waits}

<div class="api-signature">

`std::uint64_t` **`num_inflight_park_waits`** `= 0`

</div>

The number of allocation requests that waited for an in-flight chunk to retire: the only pool memory that fit was still owned by device work that had not completed, so the request paused until it did (a host running ahead of the device, under a pool at its size). Only ever rises; 0 where no request has waited.

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 71

</div>

### wrapped\_bytes {#wrapped_bytes}

<div class="api-signature">

`std::uint64_t` **`wrapped_bytes`** `= 0`

</div>

adopted subset of active\_bytes

The ADOPTED subset of [`active_bytes`](./MemoryStats.md#active_bytes): memory the runtime did not allocate but took over in place, a model file mapped straight into device-visible memory, loaded without copying. Those bytes count against the device exactly like allocated ones (on a unified-memory part they are wired 1:1), so they belong in [`active_bytes`](./MemoryStats.md#active_bytes); reported apart because the two are released differently; adopted memory goes away when the mapping is dropped, the rest when the data is freed. [`wrapped_allocs`](./MemoryStats.md#wrapped_allocs) is how many such mappings are held RIGHT NOW (a live count, unlike [`num_allocs`](./MemoryStats.md#num_allocs) above, which only ever rises). Both are 0 where the device does not adopt memory in place.

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 83

</div>

### wrapped\_allocs {#wrapped_allocs}

<div class="api-signature">

`std::uint64_t` **`wrapped_allocs`** `= 0`

</div>

mappings currently adopted

<div class="api-declared">

Declared in `ClikaRT/compute/memory_stats.h`, line 84

</div>