Andrew Kesterson
3a262bee54
Closes internal-consistency items 7 through 15. Nineteen non-static functions were in the ABI with no declaration anywhere, so no consumer could call them and any consumer could collide with them. The four gamepad_handle_* functions are the ones that mattered: controller.h declared akgl_controller_handle_button_down and three siblings that did not exist, so anything compiled against the header alone failed to link. The definitions carry the declared names now, which also closes Defects -> Known and still open item 10, and their documentation moved to the header. The rest are either declared under a "part of the internal API" block -- akgl_game_save_actors and akgl_game_load_versioncmp, which tests/game.c had to declare for itself, plus six tilemap loader helpers the untested-loader work wants to reach -- or static, which is what the four save iterators and load_objectnamemap should always have been. akgl_path_relative_from is deleted: declared nowhere, called from nowhere, never wrote its output, and leaked a pooled string on every call, so it closes Known and still open item 4 and item 40 by ceasing to exist. scripts/check_api_surface.sh keeps it closed. It reads the built library's dynamic symbol table and every public header with comments stripped, and fails on an exported akgl_* symbol that is declared nowhere. Stripping comments is the whole point -- four of these were mentioned in controller.h prose, which is how they went unnoticed. The pool-size ceilings are defined once, in heap.h, so the #ifndef override hook fires for the first time; actor.h, sprite.h and character.h were defining the same four unconditionally from headers heap.h includes above its own guard. tests/header_pool_override.c fails the compile if that regresses. Also here: (void) rather than () on the twelve no-argument entry points, AKERR_NOIGNORE only on declarations, static helpers with the akgl_ prefix dropped, and the six parameter-name mismatches. akgl_get_json_with_default had its two contexts swapped rather than merely misspelled -- the incoming one was `err` and its own was `e`, which is the name reserved for an incoming one. 24/24 pass, reindent --check clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
222 lines
10 KiB
C
222 lines
10 KiB
C
/**
|
|
* @file heap.h
|
|
* @brief The object pools. This library does not call `malloc`, it claims slots.
|
|
*
|
|
* Every runtime object -- actors, sprites, spritesheets, characters, strings --
|
|
* comes out of a fixed, statically allocated array declared here. A "heap layer"
|
|
* is one such array plus its `next`/`release` pair. Allocation is a linear scan
|
|
* for a slot whose `refcount` is 0; release decrements, and the slot is zeroed
|
|
* and unregistered when the count reaches 0.
|
|
*
|
|
* The consequence to design around is that exhaustion is a *normal* error, not
|
|
* an out-of-memory catastrophe: AKGL_ERR_HEAP means the pool is full, and the
|
|
* fix is usually a missing release rather than a bigger pool. Every ceiling
|
|
* below is overridable at compile time, so a game that needs 256 actors defines
|
|
* `AKGL_MAX_HEAP_ACTOR` before including this -- but the arrays are sized at
|
|
* compile time, so the library and everything linking it must agree.
|
|
*
|
|
* If you need a new kind of runtime object, add a layer here. Do not reach for
|
|
* the allocator.
|
|
*
|
|
* @warning The acquire functions are asymmetric: akgl_heap_next_string takes the
|
|
* reference for you, and the other four do not -- their caller is
|
|
* expected to take it, which in practice the `*_initialize` function
|
|
* does. Until one is taken the slot is still free and the next
|
|
* allocation hands out the same pointer. TODO.md, "Known and still
|
|
* open" item 8.
|
|
*/
|
|
|
|
#ifndef _AKGL_HEAP_H_
|
|
#define _AKGL_HEAP_H_
|
|
|
|
#include <akgl/sprite.h>
|
|
#include <akgl/actor.h>
|
|
#include <akgl/character.h>
|
|
#include <akgl/staticstring.h>
|
|
#include <akerror.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
|
|
|
|
/** @brief The actor pool. Public so the render and physics sweeps can walk it directly instead of going through the registry. */
|
|
extern akgl_Actor akgl_heap_actors[AKGL_MAX_HEAP_ACTOR];
|
|
/** @brief The sprite pool. 16 per actor, on the assumption of one sprite per state combination. */
|
|
extern akgl_Sprite akgl_heap_sprites[AKGL_MAX_HEAP_SPRITE];
|
|
/** @brief The spritesheet pool. Sized like the sprite pool, though sharing means far fewer are used in practice. */
|
|
extern akgl_SpriteSheet akgl_heap_spritesheets[AKGL_MAX_HEAP_SPRITESHEET];
|
|
/** @brief The character pool. */
|
|
extern akgl_Character akgl_heap_characters[AKGL_MAX_HEAP_CHARACTER];
|
|
/** @brief The string pool. Every entry is PATH_MAX bytes, so this is the largest of the five by a wide margin. */
|
|
extern akgl_String akgl_heap_strings[AKGL_MAX_HEAP_STRING];
|
|
|
|
/**
|
|
* @brief Zero every pool, marking every slot free.
|
|
*
|
|
* Call once at startup, before anything allocates. 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_game_init calls it for you.
|
|
*
|
|
* @return `NULL`. There is no failure path today -- it is a series of `memset`s
|
|
* -- but check it anyway; the signature exists so a layer that needs
|
|
* real setup has somewhere to report from.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_init(void);
|
|
/**
|
|
* @brief Zero the actor pool only.
|
|
*
|
|
* Split out from akgl_heap_init so a caller can reset the actors between levels
|
|
* while keeping the loaded sprites, sheets, and characters -- those are the
|
|
* expensive ones, since they own textures. Pair it with
|
|
* akgl_registry_init_actor, which clears the matching registry.
|
|
*
|
|
* @return `NULL`. No failure path today; see akgl_heap_init.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_init_actor(void);
|
|
/**
|
|
* @brief Claim a free actor slot.
|
|
* @param dest Receives a pointer to the free slot. Required, and **not**
|
|
* checked -- a `NULL` here is a crash, not an error context. The
|
|
* slot is *not* zeroed and its `refcount` is not incremented; it
|
|
* stays free until akgl_actor_initialize takes the reference.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKGL_ERR_HEAP If every one of the #AKGL_MAX_HEAP_ACTOR slots is in use.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_actor(akgl_Actor **dest);
|
|
/**
|
|
* @brief Claim a free sprite slot.
|
|
* @param dest Receives a pointer to the free slot. Required and unchecked; not
|
|
* zeroed, and no reference taken. See akgl_heap_next_actor.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKGL_ERR_HEAP If every one of the #AKGL_MAX_HEAP_SPRITE slots is in use.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_sprite(akgl_Sprite **dest);
|
|
/**
|
|
* @brief Claim a free spritesheet slot.
|
|
* @param dest Receives a pointer to the free slot. Required and unchecked; not
|
|
* zeroed, and no reference taken. See akgl_heap_next_actor.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKGL_ERR_HEAP If every one of the #AKGL_MAX_HEAP_SPRITESHEET slots is
|
|
* in use.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_spritesheet(akgl_SpriteSheet **dest);
|
|
/**
|
|
* @brief Claim a free character slot.
|
|
* @param dest Receives a pointer to the free slot. Required and unchecked; not
|
|
* zeroed, and no reference taken. See akgl_heap_next_actor.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKGL_ERR_HEAP If every one of the #AKGL_MAX_HEAP_CHARACTER slots is in
|
|
* use.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_character(akgl_Character **dest);
|
|
/**
|
|
* @brief Claim a free string slot, and take the reference on it.
|
|
*
|
|
* The odd one out: this *does* increment `refcount`, so the slot is yours the
|
|
* moment it returns and stays yours until you call akgl_heap_release_string.
|
|
* That is what makes the scratch-buffer idiom -- claim, use, release in
|
|
* `CLEANUP` -- safe. The contents are whatever the last holder left; call
|
|
* akgl_string_initialize if you need it clean.
|
|
*
|
|
* @param dest Receives a pointer to the claimed slot. Required and **not**
|
|
* checked -- a `NULL` here is a crash, not an error context.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKGL_ERR_HEAP If every one of the #AKGL_MAX_HEAP_STRING slots is in
|
|
* use. In practice this means a missing release somewhere, not a pool
|
|
* that is genuinely too small.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_next_string(akgl_String **dest);
|
|
|
|
/**
|
|
* @brief Drop a reference to an actor, tearing it down when the last one goes.
|
|
*
|
|
* At zero it releases every child recursively, clears the actor's entry from
|
|
* #AKGL_REGISTRY_ACTOR, and zeroes the slot.
|
|
*
|
|
* @param ptr The actor to release. Required. A slot whose `refcount` is already
|
|
* 0 is re-torn-down rather than rejected, which is harmless on a
|
|
* zeroed slot and destructive on a live one that was never
|
|
* registered.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p ptr is `NULL`.
|
|
*
|
|
* @warning Children are released unconditionally, and the recursion has no cycle
|
|
* check: an actor reachable from its own child list recurses until the
|
|
* stack runs out.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_actor(akgl_Actor *ptr);
|
|
/**
|
|
* @brief Drop a reference to a sprite, tearing it down when the last one goes.
|
|
*
|
|
* At zero it clears the sprite's entry from #AKGL_REGISTRY_SPRITE and zeroes the
|
|
* slot. The spritesheet it pointed at is *not* released -- the sprite only
|
|
* borrowed it.
|
|
*
|
|
* @param ptr The sprite to release. Required.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p ptr is `NULL`.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_sprite(akgl_Sprite *ptr);
|
|
/**
|
|
* @brief Drop a reference to a spritesheet, destroying its texture when the last one goes.
|
|
*
|
|
* The only release that frees a resource outside the pool: at zero it clears the
|
|
* entry from #AKGL_REGISTRY_SPRITESHEET, 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.
|
|
*
|
|
* @param ptr The spritesheet to release. Required.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p ptr is `NULL`.
|
|
*
|
|
* @note Destroying a texture is a main-thread operation in SDL, so this must be
|
|
* called from the thread that owns the renderer.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_spritesheet(akgl_SpriteSheet *ptr);
|
|
/**
|
|
* @brief Drop a reference to a character, tearing it down when the last one goes.
|
|
*
|
|
* At zero it clears the entry from #AKGL_REGISTRY_CHARACTER and zeroes the slot.
|
|
*
|
|
* @param ptr The character to release. Required.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p ptr is `NULL`.
|
|
*
|
|
* @note At zero it also 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, and then
|
|
* destroys the `SDL_PropertiesID` holding the map. Before 0.5.0 it did
|
|
* neither, so loading and releasing characters level by level exhausted
|
|
* the sprite pool and leaked a property set per character.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_character(akgl_Character *ptr);
|
|
/**
|
|
* @brief Drop a reference to a pooled string, zeroing it when the last one goes.
|
|
*
|
|
* Strings are not registered anywhere, so this is just the reference count and a
|
|
* wipe. It is safe to call on a string a function may or may not have claimed,
|
|
* which is why the `CLEANUP` blocks in this library call it unconditionally.
|
|
*
|
|
* @param ptr The string to release. Required -- unlike the pattern elsewhere, a
|
|
* `NULL` here is an error rather than a no-op, so `CLEANUP` blocks
|
|
* wrap it in `IGNORE()`.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p ptr is `NULL`.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_heap_release_string(akgl_String *ptr);
|
|
|
|
#endif //_AKGL_HEAP_H_
|