# 05. The heap libakgl does not call `malloc`. Every runtime object comes out of a fixed, statically allocated array declared in `include/akgl/heap.h`, and "allocation" is a linear scan for a slot whose `refcount` is zero. **The consequence to design around is that exhaustion is an ordinary error, not an out-of-memory catastrophe.** `AKGL_ERR_HEAP` is a status you can handle. It is also, almost always, a missing release rather than a pool that is genuinely too small. ## The eight pools A "heap layer" is one array plus its `next`/`release` pair. There are five: | Layer | Ceiling | Default | Element | Total | |---|---|---|---|---| | Actor | `AKGL_MAX_HEAP_ACTOR` | 64 | 400 B | 25 KiB | | Sprite | `AKGL_MAX_HEAP_SPRITE` | 1024 | 176 B | 176 KiB | | Spritesheet | `AKGL_MAX_HEAP_SPRITESHEET` | 1024 | 536 B | 536 KiB | | Character | `AKGL_MAX_HEAP_CHARACTER` | 256 | 184 B | 46 KiB | | String | `AKGL_MAX_HEAP_STRING` | 256 | 4100 B | 1.0 MiB | The whole thing is about 1.8 MiB of BSS, and **the string pool is more than half of it** because every `akgl_String` is `PATH_MAX` bytes whether it holds a path or the four characters `"0.0"`. The ceilings are all `#ifndef`-guarded: ```c excerpt=include/akgl/heap.h #ifndef AKGL_MAX_HEAP_ACTOR #define AKGL_MAX_HEAP_ACTOR 64 #endif #ifndef AKGL_MAX_HEAP_SPRITE #define AKGL_MAX_HEAP_SPRITE (AKGL_MAX_HEAP_ACTOR * 16) #endif #ifndef AKGL_MAX_HEAP_SPRITESHEET #define AKGL_MAX_HEAP_SPRITESHEET AKGL_MAX_HEAP_SPRITE #endif #ifndef AKGL_MAX_HEAP_CHARACTER #define AKGL_MAX_HEAP_CHARACTER 256 #endif #ifndef AKGL_MAX_HEAP_STRING #define AKGL_MAX_HEAP_STRING 256 #endif ``` The sprite pool is sixteen per actor, on the assumption of one sprite per state combination. The spritesheet pool is sized to match, though sharing by resolved path means far fewer are used in practice. The five arrays are `extern` and public — `akgl_heap_actors`, `akgl_heap_sprites`, `akgl_heap_spritesheets`, `akgl_heap_characters`, `akgl_heap_strings` — so the render and physics sweeps can walk them directly instead of going through a registry. `akgl_game_update` does exactly that. ### The ceilings are a compile-time ABI constraint This is the part that bites, and it does not announce itself. The arrays are sized at compile time. Defining `AKGL_MAX_HEAP_ACTOR` to 256 before including `heap.h` changes the *declared* extent of `akgl_heap_actors` in your translation unit — but `src/heap.c` was compiled with whatever the library was built with, and that is where the storage actually lives. Mismatch the two and your code indexes past the end of an array that is still 64 entries long, in another object file, with no diagnostic anywhere. ```text your game.c libakgl.so ------------------------ ------------------------ #define AKGL_MAX_HEAP_ACTOR 256 (built with the default 64) #include akgl_Actor akgl_heap_actors[64]; akgl_heap_actors[200] ------------------> off the end. No warning. ``` **Raise a ceiling for the whole build or not at all.** With `add_subdirectory`, put it in a `target_compile_definitions` that reaches libakgl's own sources as well as yours. Against an installed `libakgl.so`, you cannot change it at all without rebuilding and reinstalling the library, and the soname does not encode it — so a rebuilt game against an old installed library is a silent overrun, not a link error. ## Claiming and releasing Each layer has an acquire and a release: | Layer | Acquire | Release | |---|---|---| | Actor | `akgl_heap_next_actor` | `akgl_heap_release_actor` | | Sprite | `akgl_heap_next_sprite` | `akgl_heap_release_sprite` | | Spritesheet | `akgl_heap_next_spritesheet` | `akgl_heap_release_spritesheet` | | Character | `akgl_heap_next_character` | `akgl_heap_release_character` | | String | `akgl_heap_next_string` | `akgl_heap_release_string` | Every acquire raises `AKGL_ERR_HEAP` and nothing else. Every release raises `AKERR_NULLPOINTER` and nothing else. Full signatures are in the Doxygen reference; the behaviour worth knowing is below. **None of the `next_*` functions checks `dest`.** A `NULL` there is a crash, not an error context. That is deliberate — the check would cost a branch on the allocation path — but it means these are the functions where you validate your own argument first. **None of them zeroes the slot either.** What you get back is whatever the previous holder left. The `*_initialize` functions `memset` before they do anything else, which is why the normal shape is acquire-then-initialize and never acquire-then-use. ### The refcount asymmetry This is the one thing about the heap that will surprise you, and it is a known defect rather than a design (`TODO.md`, "Known and still open" item 8; also the `@warning` on `heap.h` itself). | Acquire | Takes the reference? | Who takes it | |---|---|---| | `akgl_heap_next_string` | **Yes** — `refcount` is 1 on return | the acquire itself | | `akgl_heap_next_actor` | No | `akgl_actor_initialize` | | `akgl_heap_next_sprite` | No | `akgl_sprite_initialize` | | `akgl_heap_next_spritesheet` | No | `akgl_spritesheet_initialize` | | `akgl_heap_next_character` | No | `akgl_character_initialize` | **Until a reference is taken, the slot is still free and the next acquire hands out the same pointer.** Seven of the eight acquires therefore leave a window in which two callers can be holding the same object, and the window closes only when `*_initialize` runs. In practice you never see it, because the four are always immediately followed by their initializer — which is exactly why the asymmetry has survived. Write them adjacent and nothing can get in between: ```c #include #include #include #include /* Claim an actor slot and take the reference on it. */ akerr_ErrorContext AKERR_NOIGNORE *spawn_actor(akgl_Actor **dest, char *name) { akgl_Actor *obj = NULL; PREPARE_ERROR(errctx); FAIL_ZERO_RETURN(errctx, dest, AKERR_NULLPOINTER, "NULL destination"); FAIL_ZERO_RETURN(errctx, name, AKERR_NULLPOINTER, "NULL name"); PASS(errctx, akgl_heap_next_actor(&obj)); /* obj->refcount is still 0. The slot is not yours yet. */ PASS(errctx, akgl_actor_initialize(obj, name)); /* obj->refcount is 1 now, and the actor is in AKGL_REGISTRY_ACTOR. */ *dest = obj; SUCCEED_RETURN(errctx); } ``` You do not have to take that on trust. This program is compiled, linked against the library and run by the test suite, and the output below it is what it actually prints: ```c run=akglapp akgl_Actor *first = NULL; akgl_Actor *second = NULL; akgl_String *str = NULL; /* A string acquire takes the reference for you. */ PASS(errctx, akgl_heap_next_string(&str)); printf("string refcount after acquire: %d\n", str->refcount); /* An actor acquire does not. */ PASS(errctx, akgl_heap_next_actor(&first)); printf("actor refcount after acquire: %d\n", first->refcount); /* So a second acquire, before the initializer runs, finds the same free slot. */ PASS(errctx, akgl_heap_next_actor(&second)); printf("same slot handed out twice: %s\n", (first == second) ? "yes" : "no"); /* Initializing is what takes the reference and closes the window. */ PASS(errctx, akgl_actor_initialize(first, "player")); printf("actor refcount after init: %d\n", first->refcount); PASS(errctx, akgl_heap_next_actor(&second)); printf("now a distinct slot: %s\n", (first == second) ? "no" : "yes"); PASS(errctx, akgl_heap_release_actor(first)); PASS(errctx, akgl_heap_release_string(str)); ``` ```output string refcount after acquire: 1 actor refcount after acquire: 0 same slot handed out twice: yes actor refcount after init: 1 now a distinct slot: yes ``` Note also that a failure between the two — `akgl_actor_initialize` rejecting the name, say — needs no cleanup, precisely because nothing was claimed. That is the one thing the asymmetry is good for. The string layer is the opposite and is safe on its own, which is what makes the scratch-buffer idiom below work. ### What each release actually does They all decrement, and they all do the teardown when the count reaches zero. What the teardown *is* differs, and two of them reach outside the pool: - **`akgl_heap_release_actor`** releases every non-`NULL` child recursively, clears the actor's entry from `AKGL_REGISTRY_ACTOR`, and zeroes the slot. The recursion has **no cycle check**: an actor reachable from its own child list recurses until the stack runs out. - **`akgl_heap_release_sprite`** clears the `AKGL_REGISTRY_SPRITE` entry and zeroes the slot. **It does not release the spritesheet** — the sprite only borrowed it. - **`akgl_heap_release_spritesheet`** clears the registry entry, **destroys the `SDL_Texture`**, and zeroes the slot. Any sprite still pointing at the sheet is left with a dangling pointer, since nothing takes a reference on a sheet on a sprite's behalf. Destroying a texture is a main-thread operation in SDL, so this must be called from the thread that owns the renderer. - **`akgl_heap_release_character`** walks the state-to-sprite map with `akgl_character_state_sprites_iterate` and `AKGL_ITERATOR_OP_RELEASE`, giving back every reference `akgl_character_sprite_add` took, then destroys the `SDL_PropertiesID` holding the map, clears the registry entry, and zeroes the slot. - **`akgl_heap_release_string`** zeroes the character data. Strings are not registered anywhere, so that is all there is to it. One shared hazard: **a slot whose `refcount` is already 0 is re-torn-down rather than rejected.** Harmless on a zeroed slot, destructive on a live one that was never registered. `akgl_heap_release_string` is the exception to the library's usual `NULL`-is-a-no-op convention: a `NULL` here is `AKERR_NULLPOINTER`, which is why every `CLEANUP` block in the library wraps it in `IGNORE()`. ## `akgl_String` A pooled string is a `refcount` and a `PATH_MAX` buffer: ```c excerpt=include/akgl/staticstring.h /** @brief Provides a fixed-capacity, heap-managed string buffer. */ typedef struct { int refcount; /**< Pool bookkeeping; 0 means the slot is free. Owned by the heap layer. */ char data[AKGL_MAX_STRING_LENGTH]; /**< The characters. Not guaranteed NUL-terminated when filled to capacity. */ } akgl_String; ``` Capacity is fixed. `akgl_string_initialize` and `akgl_string_copy` **truncate rather than grow, and the truncation is silent** — they both always NUL-terminate, but they do not tell you that something was lost. If you need to know, measure first, or go through `aksl_strncpy` with the full destination size and let it raise `AKERR_OUTOFBOUNDS`. Two details that catch people: - **`akgl_heap_next_string` does not clean the buffer.** The contents are whatever the last holder left. Call `akgl_string_initialize(str, NULL)` if you need it clean — and note that `akgl_get_property` only copies the value and its terminator, leaving the rest of the buffer alone, so read the result as a C string rather than as `AKGL_MAX_STRING_LENGTH` bytes. - **Several functions claim one for you.** `akgl_get_property`, `akgl_get_json_string_value` and `akgl_get_json_array_index_string` all claim a slot when `*dest` is `NULL`, and write in place when it is not. Either way **the caller releases it.** The scratch-buffer idiom is claim, use, release unconditionally in `CLEANUP`: ```c #include #include #include #include #include #include /* The scratch-string idiom: claim, use, release unconditionally in CLEANUP. */ akerr_ErrorContext AKERR_NOIGNORE *screen_width(int *dest) { akgl_String *value = NULL; PREPARE_ERROR(errctx); FAIL_ZERO_RETURN(errctx, dest, AKERR_NULLPOINTER, "NULL destination"); ATTEMPT { CATCH(errctx, akgl_heap_next_string(&value)); CATCH(errctx, akgl_get_property("game.screenwidth", &value, "800")); CATCH(errctx, aksl_atoi(value->data, dest)); } CLEANUP { IGNORE(akgl_heap_release_string(value)); } PROCESS(errctx) { } FINISH(errctx, true); SUCCEED_RETURN(errctx); } ``` The `CLEANUP` block runs on every path out of the `ATTEMPT`, which is the whole reason the release goes there and not after the last `CATCH`. **Never use a `*_RETURN` macro inside that `ATTEMPT`** — it returns past `CLEANUP` and leaks the slot. That mistake has shipped in this library before. ## Reading `AKGL_ERR_HEAP` When a pool is exhausted the message names the layer: ```text Unable to find unused string on the heap ``` Before you raise the ceiling, look for the missing release. The realistic causes, in the order they actually happen: 1. **A string claimed and never released.** By far the most common: the pool is 256 slots and every `akgl_get_property` call can claim one. A per-frame read that forgets the release exhausts it in four seconds at 60 Hz. 2. **A `*_RETURN` macro inside an `ATTEMPT`**, skipping the `CLEANUP` that held the release. 3. **A `return` out of a `HANDLE` block.** That leaks a libakerror context slot rather than an akgl one, and shows up as `"Unable to pull an error context from the array!"` on the 129th call — different pool, same shape of bug. 4. **Characters reloaded per level without releasing the previous ones**, which exhausts the *sprite* pool rather than the character pool, since each character holds a reference per bound state. Only after all four are ruled out is the ceiling actually too small — and a game that genuinely needs 256 actors should say so once, for the whole build, per the ABI note above. ## Initialization and reset `akgl_heap_init` zeroes all eight pools. `akgl_game_init` calls it for you, before any registry exists. **Calling it again is a reset, not a refresh.** It does not release textures, clear registries, or consult reference counts, so every live object becomes a dangling pointer and every registry entry points at a zeroed slot. `akgl_heap_init_actor` zeroes the actor pool only, which is what makes it usable between levels: the sprites, sheets and characters are the expensive ones because they own textures. Pair it with `akgl_registry_init_actor`, the one registry initializer that destroys the old property set before creating the replacement. See [Chapter 6](06-the-registry.md). Both return `NULL` and have no failure path today — they are a series of `memset`s. Check them anyway; the signature exists so a layer that needs real setup has somewhere to report from. ## If you need a new kind of object Add a layer here. Do not reach for the allocator: `AGENTS.md` makes that a standing rule, and a `malloc` in the middle of a frame is the failure mode the pools exist to remove. A layer is an array, an `AKGL_MAX_HEAP_*` ceiling, a `next`, and a `release` — five things, all visible in `src/heap.c`. ## Where to go next - [Chapter 4](04-errors.md) — `AKGL_ERR_HEAP` in the status tables. - [Chapter 6](06-the-registry.md) — the registries the releases clear entries from. - [Chapter 22](22-appendix-limits.md) — every `AKGL_MAX_*` in one place.