Take libakerror 2.0.1, and guard the exit status it fixes

2.0.0 makes the error pool and the status registry thread safe, and it is an ABI
break carrying the soname to libakerror.so.2. The break is a quiet one:
__akerr_last_ignored became thread-local and akerr_next_error() now returns a
context that already holds a reference, so objects compiled against a 1.x header
and linked against 2.x count every reference twice and never give a slot back.
Nothing about that fails to link, which is exactly what a guard is for --
include/akbasic/error.h feature-tests AKERR_THREAD_SAFE instead of
AKERR_FIRST_CONSUMER_STATUS, which 2.0.0 also still defines and which therefore
no longer distinguishes anything.

2.0.1 is the release this band needed most. The default unhandled-error handler
ended in exit(errctx->status), and a process exit status is one byte:
AKBASIC_ERR_BASE is 512, and 512 truncates to 0, so an unhandled
AKBASIC_ERR_SYNTAX reported success to anything watching $?. Every other code in
the band came out as some unrelated error's number. akerr_exit() substitutes 125
for anything a byte cannot carry, and a probe raising AKBASIC_ERR_DEVICE through
FINISH_NORETURN now exits 125 rather than 7.

It was latent here rather than live -- src/main.c handles the context and returns
EXIT_FAILURE, and every test with a top-level ATTEMPT carries a HANDLE_DEFAULT --
but "no caller relies on it today" is not a property a header can keep true.
tests/version_check.c asserts the mapping and fails if AKBASIC_ERR_BASE ever
stops truncating to zero, because that is the day this stops being about our base.

Chapter 10 gains a threading section: libakerror is safe from any thread now, and
this interpreter is not and has no lock anywhere in it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-01 08:00:24 -04:00
parent 16b38c1138
commit 8077806598
7 changed files with 123 additions and 23 deletions

View File

@@ -9,18 +9,44 @@
#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 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:
*
* libakerror publishes no version macro, so this feature-tests on
* AKERR_FIRST_CONSUMER_STATUS, which that release introduced. Same guard
* libakstdlib and libakgl already carry.
* - `__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_FIRST_CONSUMER_STATUS
#error "libakbasic requires libakerror >= 1.0.0: the akerror.h on the include path predates the status registry. Rebuild and reinstall libakerror."
#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
/*