Tachikoma
5061419768
0.9.0 is the akgl_ui subsystem: a vendored clay, an arena, menus, HUDs and dialogs, reached through a new akgl/ui.h this project does not include. Every header the akbasic_akgl target actually compiles against is byte-identical to 0.8.0, so unlike the 0.8.0 bump there is no sizeof to get wrong. The floor in include/akbasic/akgl.h moves to 0.9.0 anyway, on the standing rule that the soname carries MAJOR.MINOR while the major is 0. It does not configure as it stands. 0.9.0 moved eight test property calls off set_tests_properties -- correctly, because that command splits a semicolon-separated value and had been silently reducing its LD_LIBRARY_PATH prepend list to one directory -- onto set_property(TEST ...). This repository suppresses add_test() while it pulls its dependencies in, so those test names do not exist, and set_property errors on an unknown test name where set_tests_properties was silent: eight hard configure failures. Shadow set_property in its TEST form only; every other form has to pass through, since the dependencies set target and directory properties their own builds need. libakgl's status band grew to seven codes with AKGL_ERR_UI and it now owns 256 to 262, so the coordinated range map, docs/15-error-codes.md and both header comments follow. TODO.md section 5's persistent-drawing-layer item still stands: 0.9.0's arena draws inside the frame like everything else, and there is still no render-to-texture layer. Both configurations build and both suites pass -- 110/110 without libakgl, 111/111 with it, akgl_typing included. Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
107 lines
5.4 KiB
C
107 lines
5.4 KiB
C
/**
|
|
* @file error.h
|
|
* @brief Declares akbasic's status codes and the registry claim for them.
|
|
*/
|
|
|
|
#ifndef _AKBASIC_ERROR_H_
|
|
#define _AKBASIC_ERROR_H_
|
|
|
|
#include <akerror.h>
|
|
|
|
/*
|
|
* libakerror 2.0.0 is the floor, raised from 1.0.0 because 2.0.0 is an ABI break
|
|
* that a compile against the wrong header cannot survive quietly:
|
|
*
|
|
* - `__akerr_last_ignored` became thread-local. `IGNORE` expands at *our* call
|
|
* site, so our objects reference that symbol under whichever storage model
|
|
* the header on the include path declared.
|
|
* - `akerr_next_error()` now returns a context that already holds a reference,
|
|
* and `ENSURE_ERROR_READY` no longer increments. Objects compiled against a
|
|
* 1.x header count every reference twice and never give a slot back.
|
|
*
|
|
* Neither is a compile error. Both are a pool that leaks or a use-after-free,
|
|
* which is exactly the class of mismatch a guard is for.
|
|
*
|
|
* libakerror still publishes no version macro, so this feature-tests on
|
|
* AKERR_THREAD_SAFE, which 2.0.0 introduced and writes into the generated header
|
|
* as 1 or 0 -- so `#ifndef` is the right test and `#if` is not. It replaces the
|
|
* AKERR_FIRST_CONSUMER_STATUS test this carried for 1.0.0, which 2.0.0 also
|
|
* still defines and which therefore no longer distinguishes anything.
|
|
*/
|
|
#ifndef AKERR_THREAD_SAFE
|
|
#error "libakbasic requires libakerror >= 2.0.0: the akerror.h on the include path predates the thread-safe error pool. Rebuild and reinstall libakerror."
|
|
#endif
|
|
|
|
/*
|
|
* 2.0.1 additionally fixes an exit status this band made worse than most.
|
|
* `akerr_default_handler_unhandled_error()` used to end in `exit(errctx->status)`
|
|
* and a process exit status is one byte, so a consumer status came out truncated
|
|
* -- and **AKBASIC_ERR_BASE is 512, which truncates to 0**. An unhandled
|
|
* `AKBASIC_ERR_SYNTAX` reported success to whatever was watching `$?`. It exits
|
|
* AKERR_EXIT_STATUS_UNREPRESENTABLE (125) now.
|
|
*
|
|
* Nothing here calls `exit()` on a status -- `src/main.c` handles the context and
|
|
* returns EXIT_FAILURE, and every test installs a HANDLE_DEFAULT -- so the hazard
|
|
* was latent rather than live. It is guarded anyway, because "no caller relies on
|
|
* it today" is not a property a header can keep true.
|
|
*/
|
|
#ifndef AKERR_EXIT_STATUS_UNREPRESENTABLE
|
|
#error "libakbasic requires libakerror >= 2.0.1: an unhandled status in akbasic's band would exit 0. Rebuild and reinstall libakerror."
|
|
#endif
|
|
|
|
/*
|
|
* libakerror reserves 0-255 for the host's errno values and its own AKERR_*
|
|
* codes. libakgl claims 256-262 -- five codes until 0.8.0 added
|
|
* AKGL_ERR_COLLISION and 0.9.0 added AKGL_ERR_UI, seven since. akbasic claims
|
|
* 512-767, leaving 263-511 as
|
|
* headroom for libakgl to grow into -- see MAINTENANCE.md for the coordinated
|
|
* range map, which is the only coordination there is: libakerror can enumerate
|
|
* its consumers no better than we can.
|
|
*
|
|
* **That growth is why the map is worth keeping current.** Nothing enforces the
|
|
* boundary between two libraries' bands at compile time; the first anyone would
|
|
* know of an overlap is a status printing under the wrong owner's name in a
|
|
* stack trace, which is a bad way to find out.
|
|
*
|
|
* These are absolute constants, never offsets from AKERR_LAST_ERRNO_VALUE, so a
|
|
* libc that grows an errno cannot move them. An enum rather than a chain of
|
|
* #defines so the values stay compile-time integer constants -- HANDLE expands
|
|
* to case labels, which require that.
|
|
*
|
|
* Add a code here and you must name it in akbasic_error_register(), or it prints
|
|
* as "Unknown Error" in every stack trace that carries it.
|
|
*/
|
|
#define AKBASIC_OWNER "akbasic"
|
|
|
|
enum {
|
|
AKBASIC_ERR_BASE = 512, /** Start of akbasic's reserved status range */
|
|
AKBASIC_ERR_SYNTAX = AKBASIC_ERR_BASE,
|
|
/** Parse-time grammar violation */
|
|
AKBASIC_ERR_TYPE, /** Incompatible types in an operation */
|
|
AKBASIC_ERR_UNDEFINED, /** Reference to an undefined verb, function or label */
|
|
AKBASIC_ERR_BOUNDS, /** Array subscript or pool index out of range */
|
|
AKBASIC_ERR_ENVIRONMENT, /** Environment pool exhausted or orphaned environment */
|
|
AKBASIC_ERR_VALUE, /** A value was malformed, truncated or unconvertible */
|
|
AKBASIC_ERR_STATE, /** A verb ran outside the block structure it requires */
|
|
AKBASIC_ERR_DEVICE, /** A verb needs a graphics, audio or input backend the runtime has not been given, or one that cannot do what was asked */
|
|
AKBASIC_ERR_LAST, /** One past the last real code. Not a status; tests/error_codes.c walks up to it so a new code is checked for a name without anybody remembering to widen the loop. */
|
|
AKBASIC_ERR_LIMIT = AKBASIC_ERR_BASE + 256
|
|
};
|
|
|
|
/**
|
|
* @brief Claim the akbasic status band and register a name for every code in it.
|
|
*
|
|
* Reserves the whole 256-value range in one call -- libakerror treats only an
|
|
* identical reservation as a repeat, so a subset or superset raises -- and then
|
|
* names each code through the owned entry point. Call it before anything else in
|
|
* the library. Repeating the call is a no-op.
|
|
*
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @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 *akbasic_error_register(void);
|
|
|
|
#endif // _AKBASIC_ERROR_H_
|