Andrew Kesterson
9924d74dcc
Closes internal-consistency items 1 through 6, 12 and 13. Every include guard is _AKGL_<FILE>_H_, every in-project header include is angled, and every exported function, type and global carries the akgl_ prefix. This is an ABI break; the soname goes to libakgl.so.0.5. TODO.md carries the full rename table. The renames were driven by renaming each declaration and letting the compiler find the uses, not by pattern substitution: renderer, physics and camera are also parameter and struct-member names, and a sed would have rewritten map->physics and every akgl_RenderBackend *renderer parameter without a word. Item 4 turned out not to be cosmetic. The library exported a global called renderer and tests/character.c defined an SDL_Renderer *renderer of its own; the executable's definition preempted the library's, akgl_sprite_load_json read a SDL_Renderer * through an akgl_RenderBackend *, and every texture load in that suite failed. The suite reported success anyway, because libakerror's unhandled-error handler ends in exit(errctx->status), exit keeps only the low byte, and AKGL_ERR_SDL is exactly 256. So character had been green while running one of its four tests, and every suite in the tree was unable to fail on the most common status in a library built on SDL. Both are fixed. tests/testutil.h gains TEST_TRAP_UNHANDLED_ERRORS(), which collapses any status a byte cannot carry onto 1, and every suite installs it. character binds a real backend with akgl_render_2d_bind. Its fourth test then runs for the first time and fails on a defect it has asserted all along, so akgl_heap_release_character now walks state_sprites with AKGL_ITERATOR_OP_RELEASE and destroys the property set before zeroing the slot -- TODO.md Defects item 21 and half of Carried over item 1. AKGL_TIME_ONESEC_MS said "one second in milliseconds" and held 1000000, so akgl_game_state_lock waited roughly sixteen minutes rather than one second. It is AKGL_TIME_ONEMS_NS now, the budget is its own named constant, and tests/game.c holds the mutex from a second thread to assert the wait -- the contended path had no coverage at all. Headers are self-contained and it is enforced: AKGL_PUBLIC_HEADERS drives both install() and a generated translation unit per header, so a header that ships is a header that is checked. Writing that found registry.h, which used SDL_PropertiesID in eight declarations and included no SDL header. 23/23 suites pass, memcheck is clean, reindent --check is clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
72 lines
3.4 KiB
C
72 lines
3.4 KiB
C
/**
|
|
* @file staticstring.h
|
|
* @brief A fixed-capacity string object handed out by the akgl string heap layer.
|
|
*
|
|
* The library allocates nothing at runtime, so a "string" here is a
|
|
* PATH_MAX-sized buffer claimed from the pool with akgl_heap_next_string and
|
|
* given back with akgl_heap_release_string. Capacity is fixed at compile time:
|
|
* these functions truncate rather than grow, and truncation is silent.
|
|
*/
|
|
|
|
#ifndef _AKGL_STATICSTRING_H_
|
|
#define _AKGL_STATICSTRING_H_
|
|
|
|
#include <string.h>
|
|
#include <akerror.h>
|
|
#include <limits.h>
|
|
|
|
#define AKGL_MAX_STRING_LENGTH PATH_MAX
|
|
|
|
/** @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;
|
|
|
|
/**
|
|
* @brief Set a pooled string's contents and mark the slot in use.
|
|
*
|
|
* Copies at most #AKGL_MAX_STRING_LENGTH bytes out of @p init, or zeroes the
|
|
* buffer when @p init is `NULL`, then sets `refcount` to 1. Callers normally
|
|
* reach this through akgl_heap_next_string rather than calling it directly.
|
|
*
|
|
* @param obj The pooled string to (re)initialize. Required. Its previous
|
|
* contents are discarded without inspection.
|
|
* @param init Initial contents, NUL-terminated. Optional -- `NULL` zero-fills
|
|
* the buffer instead. An @p init longer than
|
|
* #AKGL_MAX_STRING_LENGTH is truncated *and left unterminated*,
|
|
* because this is `strncpy` semantics, not `strlcpy`.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p obj is `NULL`.
|
|
*
|
|
* @note Known defect: the `NULL` @p init path zeroes `sizeof(akgl_String)`
|
|
* bytes starting at `data`, which is four bytes past the end of the
|
|
* buffer -- `refcount` sits in front of it. TODO.md, "Known and still
|
|
* open" item 6.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_string_initialize(akgl_String *obj, char *init);
|
|
/**
|
|
* @brief Copy the contents of one pooled string into another.
|
|
*
|
|
* A bounded `strncpy` between two already-claimed pool slots. It copies bytes
|
|
* only: `refcount` is left alone, so @p dst keeps whatever pool state it had.
|
|
*
|
|
* @param src Source string. Required. Read up to @p count bytes.
|
|
* @param dst Destination string. Required. Overwritten in place; the pool
|
|
* slot must already have been claimed.
|
|
* @param count Maximum bytes to copy. 0 selects #AKGL_MAX_STRING_LENGTH, the
|
|
* whole buffer. A @p count shorter than the source truncates
|
|
* without writing a terminator; a @p count longer than the source
|
|
* zero-pads the remainder, per `strncpy`. Values above
|
|
* #AKGL_MAX_STRING_LENGTH overrun both buffers and are not
|
|
* rejected.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p src or @p dst is `NULL`.
|
|
* @throws errno Whatever `errno` holds if `strncpy` returns something other
|
|
* than @p dst. In practice `strncpy` always returns its destination, so
|
|
* this path is unreachable rather than merely rare.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_string_copy(akgl_String *src, akgl_String *dst, int count);
|
|
#endif //_AKGL_STATICSTRING_H_
|