On this page

State store

ui::store keeps a block of memory under a 64 bit key for as long as the context lives. It is how a widget or an app keeps state that has nowhere else to go, without a map of its own.

Calling store

store(u, key, bytes, drop, fresh) returns the block kept under key.

  • The first call allocates bytes zeroed and sets *fresh to true. Every later call returns the same block with *fresh false, so set it up when it is fresh.
  • Asking for more bytes than the block holds grows it. The old bytes are kept, the new tail is zeroed, and the pointer may move. Asking for fewer returns the block as it is. Nothing else ever moves it.
  • A non null drop replaces the one stored. It runs on the block just before it is freed.
  • It returns null when bytes is zero or memory runs out, and logs the second case.

Picking a key

The key is used as given and is not mixed with the element it is called under. Use ui::last_id right after declaring the element the state belongs to, or a hash of your own. Kit components keep their state under a hash of their own name. An element id is only stable when the element is: give loop bodies a ui::key so an id follows its item rather than its position. See how widgets work.

core_store.cpp
#include "isolenui/ui/ui.h"

#include <stdlib.h>

struct history {
    float* samples;
    uint32_t count;
    uint32_t cap;
};

// runs once when the context goes, before the record is freed
static void history_drop(void* data)
{
    free(static_cast<history*>(data)->samples);
}

static void cpu_graph(ui::ctx* u, const char* name, float sample)
{
    ui::key(u, name);
    ui_box(u, ui::col().pad(8.0f).gap(4.0f))
    {
        // the box id is stable because of the key, so the record is too
        bool fresh = false;
        history* h = static_cast<history*>(
            ui::store(u, ui::last_id(u), sizeof(history), history_drop, &fresh));
        if (!h) {
            return;
        }
        if (fresh) {
            h->cap = 120u;
            h->samples = static_cast<float*>(calloc(h->cap, sizeof(float)));
        }
        if (h->samples) {
            h->samples[h->count++ % h->cap] = sample;
        }
        ui::text(u, name);
    }
}

// how the state store is doing, for a debug overlay
static void store_line(ui::ctx* u)
{
    ui::store_stats s = {};
    ui::store_stats_of(u, &s);
    ui::textf(u, ui::mono(u), "%u live %u kept of %u, %u keys, %u of %u elements",
              s.live, s.kept, s.cap, s.keys, s.elems, s.elem_cap);
}

When memory goes

Store blocks are never evicted. They are freed only by ctx_destroy, which runs each drop first. There is no call to free one early, so keep the set of keys bounded; a new key per passing item grows the store for the life of the context. Rows of a virtual list should key by a stable row id, not by their place on screen.

Separately, the core keeps one small record per element id: its last rect and state, its eased values and its scroll offsets. A record not declared in a frame is kept while it holds an eased value or a non zero scroll offset, and freed otherwise. So a view that leaves the tree, a hidden tab say, comes back at the same scroll position, and a record with nothing in it costs nothing. The record pool doubles when full and logs when it does. A kept record forgets its rect, so rect_of and state_of read empty for an element that was not declared last frame.

The same id declared twice in one frame is pushed along to a new id with a warning, and its state does not carry over. That is what a loop without keys does.

store_stats

store_stats_of(u, &s) fills a store_stats, for a debug overlay or a log line.

FieldCounts
liveElement records seen in the last frame.
keptRecords not seen but kept for an eased value or a scroll offset.
capRecord capacity before the pool grows again.
keysBlocks held by store.
elems, elem_capElements the last frame declared, and the most one frame can declare.
arenaText bytes the last frame used, out of a 65536 byte arena.
evictedEmpty records freed since the counter was last reset. It is logged and reset once at least 1800 frames have passed since the previous reset, so it is a recent count, not a lifetime total.

Last updated 6 October 2026