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>
79 lines
3.8 KiB
C
79 lines
3.8 KiB
C
/**
|
|
* @file error.h
|
|
* @brief Declares the public error API.
|
|
*/
|
|
|
|
#ifndef _AKGL_ERROR_H_
|
|
#define _AKGL_ERROR_H_
|
|
|
|
#include <akerror.h>
|
|
|
|
/*
|
|
* libakerror 1.0.0 is the floor. That release moved the status-name table into a
|
|
* private registry -- AKERR_MAX_ERR_VALUE and __AKERR_ERROR_NAMES are gone, the
|
|
* registry entry points raise akerr_ErrorContext * instead of returning int, and
|
|
* the library gained an soname -- so a translation unit that pairs this header
|
|
* with a pre-1.0.0 akerror.h is an ABI mismatch, not just a compile problem.
|
|
*
|
|
* libakerror publishes no version macro, so this feature-tests on
|
|
* AKERR_FIRST_CONSUMER_STATUS, which that release introduced, rather than on a
|
|
* version number that does not exist. Without the guard an embedded build is
|
|
* fine but a stale installed header fails much further in, on the AKGL_ERR_*
|
|
* codes below and again inside src/heap.c.
|
|
*
|
|
* See deps/libakerror/UPGRADING.md.
|
|
*/
|
|
#ifndef AKERR_FIRST_CONSUMER_STATUS
|
|
#error "libakgl requires libakerror >= 1.0.0: the akerror.h on the include path predates the status registry. Rebuild and reinstall libakerror."
|
|
#endif
|
|
|
|
// This macro is used to silence warnings on string concatenation operations that may fail.
|
|
// e.g., combining two element of PATH_MAX into a string buffer of AKGL_STRING_MAX_LENGTH.
|
|
// We have to draw a line in the sand somewhere or we will just let our buffers grow forever
|
|
// to keep the compiler happy.
|
|
#define DISABLE_GCC_WARNING_FORMAT_TRUNCATION \
|
|
_Pragma("GCC diagnostic push") \
|
|
_Pragma("GCC diagnostic ignored \"-Wformat-truncation\"")
|
|
|
|
#define RESTORE_GCC_WARNINGS \
|
|
_Pragma("GCC diagnostic pop")
|
|
|
|
// libakerror reserves statuses 0-255 for the host's errno values and its own
|
|
// AKERR_* codes; consumers allocate from AKERR_FIRST_CONSUMER_STATUS upward.
|
|
// These are fixed offsets from that base rather than from AKERR_LAST_ERRNO_VALUE
|
|
// so that a libc which grows an errno cannot move them out from under us.
|
|
//
|
|
// akgl_error_init() reserves this whole band in one call and registers a name
|
|
// for every code below. Add a code here and you must name it there, or it
|
|
// prints as "Unknown Error" in every stack trace that carries it.
|
|
#define AKGL_ERR_OWNER "libakgl"
|
|
#define AKGL_ERR_BASE AKERR_FIRST_CONSUMER_STATUS
|
|
|
|
#define AKGL_ERR_SDL (AKGL_ERR_BASE + 0) /**< An SDL call failed; the message carries SDL_GetError() */
|
|
#define AKGL_ERR_REGISTRY (AKGL_ERR_BASE + 1) /**< A registry property or lookup operation failed */
|
|
#define AKGL_ERR_HEAP (AKGL_ERR_BASE + 2) /**< A heap pool has no free object left to hand out */
|
|
#define AKGL_ERR_BEHAVIOR (AKGL_ERR_BASE + 3) /**< A component did not behave the way its contract requires */
|
|
#define AKGL_ERR_LOGICINTERRUPT (AKGL_ERR_BASE + 4) /**< Actor logic is telling the physics simulator to skip it */
|
|
|
|
// One past the last libakgl status. The reservation is all-or-nothing -- a
|
|
// subset or superset of an existing one is refused -- so this must stay one
|
|
// past the highest code above.
|
|
#define AKGL_ERR_LIMIT (AKGL_ERR_BASE + 5)
|
|
#define AKGL_ERR_COUNT (AKGL_ERR_LIMIT - AKGL_ERR_BASE)
|
|
|
|
/**
|
|
* @brief Claim the libakgl status band and register a name for every code in it.
|
|
*
|
|
* Call this before anything else in libakgl. Every other subsystem raises
|
|
* AKGL_ERR_* codes, and a code raised before this runs carries no name into its
|
|
* stack trace. Repeating the call is a no-op, so a program that cannot order its
|
|
* initialization precisely may call it more than once.
|
|
*
|
|
* @throws AKERR_STATUS_RANGE_OVERLAP When another component already owns part of the band.
|
|
* @throws AKERR_STATUS_RANGE_FULL When libakerror has no reservation slots left.
|
|
* @throws AKERR_STATUS_NAME_FULL When libakerror's name registry is full.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_error_init(void);
|
|
|
|
#endif // _AKGL_ERROR_H_
|