From 8ae5e731db88f6950d9f8aa1c5c8d691be4f6c4d Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Thu, 19 Nov 2026 15:42:38 +0900 Subject: [PATCH 1/2] okrun names the openkal call each task of the image waits in when the program is asked to end Where the image is entered, the runner takes the program's requests to end (kal_process_stop_requested) on a task of its own that waits upon the word (run/src/waits.cpp, both runners). Each task of the image has a line: its identity (kal_task_current) and the call that waits it is in. A task takes its line as it begins (enter_image; the entering task in watch_requests) and gives it back as it returns from its entry. The calls that wait are bound through an entry that records the call on the caller's line (build.mcpp's `waits': the operations openkal.timeout bounds and its own forms of them, kal_task_wait, kal_task_join, kal_time_sleep, kal_stream_flush, kal_fs_open, kal_fs_lock, kal_net_connect, kal_net_connect_at, kal_datagram_send_to); a call that returns at once pays nothing. The table is keyed by the task's identity, as prof.cpp keeps its phases, not thread-local storage. A request writes one line per task to the error stream, within a second where the implementation bounds a write, then is acted on as before the runner took it: the program ends as the request would have ended it (kal_process_end_as_requested). An image that takes the requests over (kal_process_stop_requested, now the runner's own) is given a word the runner counts once the record is written, so the record precedes the image's own handling; on the implementation's word the image ended first and no record was written. Where the implementation reports no request or no task can be started, nothing is taken, and a measurement's report says why. build.mcpp checks that every name it treats specially is in the surface, and an own name of an interface the implementation does not provide is absent. Measured on Linux x86-64: SIGTERM, SIGINT and SIGHUP end the program with their own status after the record; the shortest call that waits pays some ten nanoseconds (a one-byte write to the null device 95 ns against 85). Test: examples/ending (a task waiting upon a word, the main task joining it; with `takes' the image took the requests over) and tools/tests/end_request.py, which asks okrun to end (SIGTERM; CTRL_BREAK_EVENT on Windows) and reads the record, the task identities the image printed and the status. CI builds the image for x86_64 and aarch64 and runs the test on every system of the run job. --- .github/workflows/ci.yml | 14 +- README.md | 33 +++++ examples/ending/app.c | 84 ++++++++++++ run/build.mcpp | 50 +++++++- run/mcpp.toml | 2 +- run/src/bindings.cpp | 40 +++++- run/src/core/run.cpp | 2 + run/src/full/run.cpp | 3 + run/src/full/seal.cpp | 1 + run/src/runner.h | 17 +++ run/src/waits.cpp | 255 +++++++++++++++++++++++++++++++++++++ tools/tests/end_request.py | 81 ++++++++++++ 12 files changed, 572 insertions(+), 10 deletions(-) create mode 100644 examples/ending/app.c create mode 100644 run/src/waits.cpp create mode 100644 tools/tests/end_request.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d5d5235..3456a0b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,7 +18,9 @@ name: CI # program of the system calls an image's library through libokrun # and through the binding openkal-bind generates, and the binding's # refusals hold. An image at its base, anywhere and unplaced -# observes the same memory (0.4.0). +# observes the same memory (0.4.0). Asked to end, okrun names the +# openkal call each task of an image waits in, then ends the +# program as the request would have (0.7.0). on: push: @@ -94,6 +96,8 @@ jobs: bash examples/build-image.sh "$arch" "out/$arch/stack.oke" examples/stack/app.c # The convention's floating-point state at the entry and in a context (0.5.3). bash examples/build-image.sh "$arch" "out/$arch/fpstate.oke" examples/fpstate/app.c + # Tasks that wait when the program is asked to end (0.7.0). + bash examples/build-image.sh "$arch" "out/$arch/ending.oke" examples/ending/app.c cp "out/$arch/hello.oke" "out/$arch/signed.oke" # The library examples/bind binds for a program of each system. bash examples/build-image.sh "$arch" "out/$arch/libmathlib.okso" examples/bind/mathlib/image/mathlib.c @@ -289,6 +293,14 @@ jobs: run: | python=python3; [ "$RUNNER_OS" = Windows ] && python=python "$python" tools/tests/record_env.py --okprof "$OKPROF" + - name: A request to end names the call each task waits in (0.7.0) + run: | + # Asked to end (SIGTERM; a console's CTRL_BREAK_EVENT on Windows), + # okrun writes the openkal call each task of the image waits in, then + # ends the program as the request would have; an image that took the + # requests over is named the same and ends by itself. + python=python3; [ "$RUNNER_OS" = Windows ] && python=python + "$python" tools/tests/end_request.py --okrun "$OKRUN" --image "out/${{ matrix.arch }}/ending.oke" - name: The same bytes run: | a='${{ matrix.arch }}' diff --git a/README.md b/README.md index f0d35a9..936d7c3 100644 --- a/README.md +++ b/README.md @@ -299,6 +299,36 @@ identity, length and modification time. A later start of the same file admits th shape alone; a file replaced or changed is compared again. A language server that starts a worker per module no longer reads its 146 MB okb at each start. +## When the program is asked to end + +A task of an image that never returns is waiting in a call of openkal or running its own code, and +a program ended by force leaves nothing to say which. Where the image is entered, the runner takes +the program's requests to end (`kal_process_stop_requested`: SIGTERM, SIGINT and SIGHUP on Linux, +macOS and FreeBSD; a console's control events on Windows) and waits for them on a task of its own +(0.7.0). Each task of the image has a line: its identity (`kal_task_current`) and the call that +waits it is in. The calls that wait are those that return only when another party acts or a time +passes (`run/build.mcpp`): the operations `openkal.timeout` bounds and its own forms of them, +`kal_task_wait`, `kal_task_join`, `kal_time_sleep`, `kal_stream_flush`, `kal_fs_open`, +`kal_fs_lock`, `kal_net_connect`, `kal_net_connect_at` and `kal_datagram_send_to`. A request +writes the lines to the runner's error stream, within a second where the implementation bounds a +write: + +```text +okrun: asked to end; the openkal call each task of the image waits in: +okrun: task 2548376 (main): kal_task_join +okrun: task 2548380: kal_task_wait +``` + +and is then acted on as it was before the runner took it: the program ends as the request would +have ended it (`kal_process_end_as_requested`), so its starter observes the same end. An image that +takes the requests over itself is given a word that the runner counts once the record is written, +and acts on each request as it always did; each request writes the record. A task in none of the +calls that wait is `in no call that waits`: it runs its own code, or a call that returns by itself. +A harness that asks a program to end and waits a moment before it ends it by force so learns what +each task was waiting for. Where the implementation reports no request to end, or no task can be +started to wait for one, nothing is taken and a request ends the program as before; a +measurement's report states which (`requests`). + ## A debugger An image's instructions and read-only data are its file's pages, so a debugger finds the image @@ -357,6 +387,9 @@ its header and calls it, on openkal and on every other system alike ([docs/bind. nothing to the runner's cache; `okrun cache` lists and removes what it keeps. - An okb states its images' chunk digests, which okrun verifies on several contexts and `okld bundle check` beside the whole digest; a changed byte is refused by either. +- Asked to end, okrun names the openkal call each task of an image waits in, with the task's + identity, and the program ends as the request would have ended it; an image that took the + requests over is named the same and ends by itself, with its own status. - libokld's SHA-256, CRC-32, ZIP reader and writer (with ZIP64) and manifest reader hold against their vectors and refusals. diff --git a/examples/ending/app.c b/examples/ending/app.c new file mode 100644 index 0000000..8e516a1 --- /dev/null +++ b/examples/ending/app.c @@ -0,0 +1,84 @@ +/* An image asked to end while its tasks wait (openkal-image 0.7.0). Its main + * task starts another, which waits upon a word nobody changes, and joins it; + * once the other has begun, the image says which task is which. okrun, asked to + * end, writes the call each task waits in --- the main task kal_task_join, the + * other kal_task_wait --- and ends the program as the request would have ended + * it. + * + * With the argument `takes', the image first takes the requests to end over + * (kal_process_stop_requested): the other task sleeps, the main task waits upon + * the request word, and once asked the image says so and returns 7. okrun + * writes the record --- kal_task_wait and kal_time_sleep --- and leaves the + * request to the image. tools/tests/end_request.py asks and reads both. */ +typedef unsigned long kal_uintptr; +typedef long kal_intptr; +typedef unsigned int kal_u32; +typedef unsigned long long kal_u64; +struct kal_stream { kal_uintptr h; }; +struct kal_task { kal_uintptr h; }; + +struct kal_stream kal_stdout(void); +kal_intptr kal_stream_write(struct kal_stream, const void*, kal_uintptr); +kal_uintptr kal_env_arg_count(void); +kal_intptr kal_env_arg(kal_uintptr, char*, kal_uintptr); +int kal_task_start(void (*entry)(void*), void* arg, struct kal_task* out); +int kal_task_join(struct kal_task); +kal_uintptr kal_task_current(void); +int kal_task_wait(const kal_u32* word, kal_u32 expected, kal_u64 timeout_ns); +int kal_task_wake(const kal_u32* word, kal_uintptr count, kal_uintptr* woken); +void kal_time_sleep(kal_u64 ns); +const kal_u32* kal_process_stop_requested(void); + +static void put(const char* s) { + unsigned long n = 0; while (s[n]) ++n; + kal_stream_write(kal_stdout(), s, n); +} +static void put_num(kal_uintptr v) { + char b[24]; int i = 23; b[i] = 0; + do { b[--i] = (char)('0' + v % 10); v /= 10; } while (v); + put(b + i); +} + +static kal_uintptr g_other; +static kal_u32 g_begun; +static kal_u32 g_never; + +static void begun(void) { + g_other = kal_task_current(); + __atomic_store_n(&g_begun, 1, __ATOMIC_RELEASE); + kal_task_wake(&g_begun, 1, 0); +} +static void waits(void* arg) { + (void)arg; + begun(); + for (;;) kal_task_wait(&g_never, 0, 0); +} +static void sleeps(void* arg) { + (void)arg; + begun(); + for (;;) kal_time_sleep(3600ull * 1000000000ull); +} + +static int takes(void) { + char a[8]; + if (kal_env_arg_count() < 2) return 0; + const kal_intptr n = kal_env_arg(1, a, sizeof a); + return n == 5 && a[0] == 't' && a[1] == 'a' && a[2] == 'k' && a[3] == 'e' && a[4] == 's'; +} + +__attribute__((visibility("default"))) int ok_main(void) { + const int taken = takes(); + const kal_u32* stop = 0; + if (taken && !(stop = kal_process_stop_requested())) { put("ending: no request reaches this program\n"); return 3; } + struct kal_task other; + if (kal_task_start(taken ? sleeps : waits, 0, &other) != 0) { put("ending: no task\n"); return 3; } + while (__atomic_load_n(&g_begun, __ATOMIC_ACQUIRE) == 0) kal_task_wait(&g_begun, 0, 0); + put("ending: main "); put_num(kal_task_current()); put(", other "); put_num(g_other); put("\n"); + if (!taken) { + kal_task_join(other); + return 0; + } + while (__atomic_load_n(stop, __ATOMIC_ACQUIRE) == 0) kal_task_wait(stop, 0, 0); + put("ending: asked to end, and the image ends by itself\n"); + return 7; +} diff --git a/run/build.mcpp b/run/build.mcpp index 8c71bad..d8f24cc 100644 --- a/run/build.mcpp +++ b/run/build.mcpp @@ -39,10 +39,30 @@ int main() { // box; every other name is the implementation's. Since 0.2 the runner // also answers openkal.prof and openkal.debug, which are a loader's (SPEC // 12.3), the word of interfaces (the implementation's and those two), and - // the program's end (where a measurement records what it measured). + // the program's end (where a measurement records what it measured). Since + // 0.7 the runner also answers the requests to end, which it took before the + // image could: an image that asks for them takes them over. std::set own{ "kal_env_arg_count", "kal_env_arg", "kal_env_image", "kal_env_loader", - "kal_interfaces", "kal_exit", "kal_abort" }; + "kal_interfaces", "kal_exit", "kal_abort", "kal_process_stop_requested" }; const std::set callbacks{ "kal_task_start", "kal_task_start_sized" }; + // THE CALLS THAT WAIT (0.7): each returns only when another party acts --- + // a task, a program, a peer --- or a time passes, so a task that does not end + // is found in one of them. openkal.timeout names the operations that would + // otherwise wait without end, and its own forms of them wait up to a bound; + // the others wait by what they are (a context joined or a word waited upon, + // a lock another holds, a named pipe opened before its other end). Each is + // entered through a record of the call on the calling task's line, which a + // request to end writes (src/waits.cpp). An operation upon a file waits for + // a device, as every operation does, and is not among them. + const std::set waits{ + "kal_stream_read", "kal_stream_write", "kal_stream_flush", "kal_time_sleep", + "kal_fs_open", "kal_fs_lock", "kal_process_wait", "kal_task_join", "kal_task_wait", + "kal_net_accept", "kal_net_connect", "kal_net_connect_at", + "kal_datagram_recv_from", "kal_datagram_send_to", + "kal_timeout_read", "kal_timeout_write", "kal_timeout_accept", "kal_timeout_recv_from", + "kal_timeout_wait_process" }; + // The interfaces a loader answers itself, whatever the implementation provides (SPEC 12.3). + const std::set loaders{ "openkal.prof", "openkal.debug" }; std::vector main_names, space_names, groups; std::map group_of; std::string group, line; @@ -58,6 +78,18 @@ int main() { group_of[line] = group; (group == "openkal.space" ? space_names : main_names).push_back(line); } + // A name this runner treats as its own, as a callback or as a call that waits + // is one the specification has: a name it dropped or renamed would be bound + // as any other, without the treatment, and nothing would say so. + auto known = [&](const std::set& names) { + for (const auto& n : names) { + if (group_of.contains(n)) continue; + std::printf("mcpp:warning=%s is not a name of %s\n", n.c_str(), surface.string().c_str()); + return false; + } + return true; + }; + if (!known(own) || !known(callbacks) || !known(waits)) return 1; // The interfaces the implementation provides; none stated is every one. std::set provided; @@ -82,11 +114,15 @@ int main() { // of the calls an image makes (okprof, 0.2) keeps its counts. for (std::size_t i = 0; i < names.size(); ++i) { const auto& n = names[i]; - // A callback of an interface the implementation does not provide is absent, as - // its other names are (0.6.3: a context cannot be started where there are none). - o << (own.contains(n) ? "OKRUN_OWN(" : - !provided.contains(group_of[n]) ? "OKRUN_ABSENT(" : - callbacks.contains(n) ? "OKRUN_CALLBACK(" : "OKRUN_BIND(") + // A name of an interface the implementation does not provide is absent, a + // callback's (0.6.3: a context cannot be started where there are none) and a + // name the runner answers (0.7: no request to end where there are no programs) + // as well, except the loader's own interfaces, which it answers everywhere. + const std::string& g = group_of[n]; + o << (!provided.contains(g) && !loaders.contains(g) ? "OKRUN_ABSENT(" : + own.contains(n) ? "OKRUN_OWN(" : + callbacks.contains(n) ? "OKRUN_CALLBACK(" : + waits.contains(n) ? "OKRUN_WAIT(" : "OKRUN_BIND(") << n << ", " << i << ")\n"; } }; diff --git a/run/mcpp.toml b/run/mcpp.toml index c959a6e..404961a 100644 --- a/run/mcpp.toml +++ b/run/mcpp.toml @@ -39,7 +39,7 @@ requires-interfaces = [ ] [build] -sources = ["src/okrun.cppm", "src/bindings.cpp", "src/adapters.cpp"] +sources = ["src/okrun.cppm", "src/bindings.cpp", "src/adapters.cpp", "src/waits.cpp"] include_dirs = ["include"] flags = [ { glob = "src/*.cpp", cxxflags = ["-fno-exceptions", "-fno-rtti"] }, diff --git a/run/src/bindings.cpp b/run/src/bindings.cpp index 5f863a2..c86120e 100644 --- a/run/src/bindings.cpp +++ b/run/src/bindings.cpp @@ -38,18 +38,43 @@ struct counted { } }; +// A CALL THAT WAITS (build.mcpp's `waits', 0.7): its name is on the calling +// task's line while it waits, where the runner watches the requests to end +// (src/waits.cpp), and counted as well where a measurement asked for calls. +template struct waited; +template +struct waited { + OKRUN_IMAGE_ABI static R call(A... a) { + const kal_u64 t0 = Counted ? kal_time_monotonic() : 0; + task_line* line = wait_begin(I); + if constexpr (returns_nothing::value) { + F(a...); + wait_end(line); + if constexpr (Counted) record_call(I, kal_time_monotonic() - t0); + } else { + R r = F(a...); + wait_end(line); + if constexpr (Counted) record_call(I, kal_time_monotonic() - t0); + return r; + } + } +}; + // A function the image passes to be entered as a new context: it is the // image's, so it is entered in the image's convention through a box. using image_entry = void (OKRUN_IMAGE_ABI*)(void*); struct box { image_entry fn; void* arg; }; // The context is the image's from its start, in the convention's -// floating-point state (SPEC 12.2). +// floating-point state (SPEC 12.2), and has a line of its own until it ends +// (0.7): returning from its entry is the only way a context ends. void enter_image(void* p) { const box b = *static_cast(p); kal_free(p, sizeof(box), alignof(box)); + task_line* line = task_begin(); okrun_fp_enter(); b.fn(b.arg); + task_end(line); } #if OKRUN_HAS_TASK @@ -117,6 +142,14 @@ OKRUN_IMAGE_ABI void own_kal_abort(const char* msg, kal_uintptr len) { profile_finish(); kal_abort(msg, len); } +#if OKRUN_HAS_PROCESS +// THE IMAGE TAKES THE REQUESTS TO END OVER (0.7). The runner took them where it +// entered the image (src/waits.cpp); from the image's first call they are the +// image's to act on, as they would have been had no runner taken them, and a +// request still writes the call each task waits in, before the image's word +// counts it. +OKRUN_IMAGE_ABI const kal_u32* own_kal_process_stop_requested(void) { return requests_taken(); } +#endif OKRUN_IMAGE_ABI int own_kal_prof_active(void) { return profile_active() ? 1 : 0; } OKRUN_IMAGE_ABI int own_kal_prof_counter(const char* name, kal_uintptr len, const volatile kal_u64* cell) { return profile_counter(name, len, cell); @@ -167,6 +200,7 @@ OKRUN_IMAGE_ABI int own_kal_prof_touch_end(void) { #define OKRUN_BIND(n, i) { #n, reinterpret_cast(&present<&::n>::call) }, #define OKRUN_OWN(n, i) { #n, reinterpret_cast(&own_##n) }, #define OKRUN_CALLBACK(n, i) { #n, reinterpret_cast(&callback_##n) }, +#define OKRUN_WAIT(n, i) { #n, reinterpret_cast(&waited<&::n, i, false>::call) }, // A name of an interface the implementation does not provide: listed, so that // every name keeps its position, and bound to nothing. #define OKRUN_ABSENT(n, i) { #n, nullptr }, @@ -178,7 +212,9 @@ const binding g_table[] = { }; #undef OKRUN_BIND +#undef OKRUN_WAIT #define OKRUN_BIND(n, i) { #n, reinterpret_cast(&counted<&::n, i>::call) }, +#define OKRUN_WAIT(n, i) { #n, reinterpret_cast(&waited<&::n, i, true>::call) }, const binding g_counted[] = { #include "surface.inc" }; @@ -190,9 +226,11 @@ static_assert(sizeof g_table / sizeof g_table[0] <= kProfiledNames, "the call co #undef OKRUN_BIND #undef OKRUN_OWN #undef OKRUN_CALLBACK +#undef OKRUN_WAIT #define OKRUN_BIND(n, i) { #n, reinterpret_cast(&present<&::n>::call) }, #define OKRUN_OWN(n, i) OKRUN_BIND(n, i) #define OKRUN_CALLBACK(n, i) OKRUN_BIND(n, i) +#define OKRUN_WAIT(n, i) OKRUN_BIND(n, i) const binding g_space[] = { #include "surface_space.inc" }; diff --git a/run/src/core/run.cpp b/run/src/core/run.cpp index 7206ca4..1d92648 100644 --- a/run/src/core/run.cpp +++ b/run/src/core/run.cpp @@ -175,6 +175,8 @@ int enter(search& s, const void* bytes, unsigned long long size, const char* nam g_state.name = name; g_state.carried = s.options && s.options->carried; g_state.started = true; + // As the full runner (0.7, src/waits.cpp): nothing where there are no processes or contexts. + watch_requests(); okld_host& h = s.host; h.reserve = &reserve; h.publish = &publish; h.release = &release; h.map = nullptr; h.granularity = &granularity; h.resolve = &resolve; diff --git a/run/src/full/run.cpp b/run/src/full/run.cpp index 6074c03..a6bdfec 100644 --- a/run/src/full/run.cpp +++ b/run/src/full/run.cpp @@ -1603,6 +1603,9 @@ int enter(search& s, const void* bytes, unsigned long long size, const char* nam prepare_host(s, true); const snapshotting snapshot = snapshot_mode(); if (snapshot == snapshotting::make) make_snapshot(s, bytes, size, name); + // The requests to end are the runner's from here, and one writes the call + // each task of the image waits in (0.7, src/waits.cpp). + watch_requests(); profile_phase("admitted"); profile_note("prefetch", s.host.prefetch == 2 ? "the touched pages and the data" : s.host.prefetch == 1 ? "the touched pages" : "nothing", 0); diff --git a/run/src/full/seal.cpp b/run/src/full/seal.cpp index a57d21a..f012482 100644 --- a/run/src/full/seal.cpp +++ b/run/src/full/seal.cpp @@ -200,6 +200,7 @@ template OKRUN_IMAGE_ABI void refuse() { asked(g_names[I].name #define OKRUN_BIND(n, i) { #n, reinterpret_cast(&refuse) }, #define OKRUN_OWN(n, i) OKRUN_BIND(n, i) #define OKRUN_CALLBACK(n, i) OKRUN_BIND(n, i) +#define OKRUN_WAIT(n, i) OKRUN_BIND(n, i) #define OKRUN_ABSENT(n, i) OKRUN_BIND(n, i) const binding g_main[] = { #include "surface.inc" diff --git a/run/src/runner.h b/run/src/runner.h index c109454..500c73d 100644 --- a/run/src/runner.h +++ b/run/src/runner.h @@ -89,6 +89,23 @@ int impl_prof_touch_end(); kal_uintptr impl_debug_props(); kal_intptr impl_debug_symbolize(kal_uintptr address, char* out, kal_uintptr cap, kal_uintptr* start); +// --- the call each task of the image waits in, when the program is asked to end (0.7, src/waits.cpp) +// +// Where the image is entered the runner takes the program's requests to end and waits for them on +// a task of its own (`watch_requests'). Each task of the image has a line, kept as it begins and +// ends (`task_begin', `task_end', bindings.cpp) and by the entry of each call that waits +// (`wait_begin', `wait_end'; build.mcpp's `waits'). A request writes the lines to the error stream +// and is then acted on as before: the program ends as the request would have ended it, unless the +// image took the requests over itself (`requests_taken', its `kal_process_stop_requested'). +struct task_line; +void watch_requests(); +task_line* task_begin(); +void task_end(task_line* line); +// `index' is the call's position among the bound names (surface.inc); null where nothing watches. +task_line* wait_begin(unsigned long index); +void wait_end(task_line* line); +const kal_u32* requests_taken(); + // --- a snapshot of an image's initialisers (0.4, src/seal.cpp) --------------- // // The bindings while they run: memory from an arena above the image's end diff --git a/run/src/waits.cpp b/run/src/waits.cpp new file mode 100644 index 0000000..1c78af8 --- /dev/null +++ b/run/src/waits.cpp @@ -0,0 +1,255 @@ +// THE CALL EACH TASK OF THE IMAGE WAITS IN, WRITTEN WHEN THE PROGRAM IS ASKED TO +// END (0.7). A harness whose time runs out first asks the program to end and +// waits a while before it ends it by force (mcpp design 2026-11-19 ยง12): a +// program ended by force leaves nothing to say what it was waiting for, and a +// task of an image that never returns is in a call of openkal or in its own +// code. Both runners' (0.6.3). +// +// WHERE THE IMAGE IS ENTERED THE RUNNER TAKES THE REQUESTS (`watch_requests'): +// a task of its own asks for the word (`kal_process_stop_requested') and waits +// upon it. Each task of the image has a line --- its identity +// (`kal_task_current') and the call that waits it is in --- taken as the task +// begins (bindings.cpp, `enter_image'; the entering task here) and kept by the +// entry of each call that waits (build.mcpp's `waits'). A request writes one +// line per task to the error stream, then is acted on as it was before the +// runner took it: the program ends as the request would have ended it +// (`kal_process_end_as_requested'), unless the image took the requests over +// itself (`requests_taken'). Such an image is given a word of the runner's, +// counted as the implementation counts its own once the record is written: on +// the implementation's word the image woke with the runner's task and could end +// the program before the record was written (measured: it ended first, and no +// record was written). +// +// A TABLE KEYED BY THE TASK'S IDENTITY, as prof.cpp keeps its phases, rather +// than thread-local storage: this library may be linked into a program that +// brings no C++ run-time, and whether a context has the toolchain's +// thread-local storage is a property an implementation states +// (KAL_TASK_PROP_THREAD_LOCAL). Only a call that waits looks its line up, so a +// call that returns at once pays nothing; the shortest call that waits pays +// some ten nanoseconds (measured on Linux x86-64: a write of one byte to the +// null device took 95 ns where it took 85, a wait upon a word that differed +// 121 ns where it took 120). +// +// Where the implementation reports no request (its word is null) or no task can +// be started to wait for one, nothing is taken: a request ends the program as +// before, without the lines, and a measurement's report says why (`requests'). +#include +#include "runner.h" + +namespace okrun { + +#if OKRUN_HAS_PROCESS && OKRUN_HAS_TASK + +struct task_line { + kal_uintptr task; // the identity; zero: free + unsigned long call; // the call's position among the bound names, one more; zero: none +}; + +namespace { + +// As many tasks as prof.cpp keeps phases for. A line is taken within kReach of +// the slot its identity hashes to, and found there. +constexpr unsigned kLines = 512; +constexpr unsigned kReach = 16; +task_line g_lines[kLines]; +// The line of a task that found none free within its reach: counted while it +// runs, so that the record says how many tasks it could not name. +task_line g_no_line; +unsigned g_unheld = 0; +int g_watched = 0; // a task of the runner's waits for the requests +int g_taken = 0; // the image took them over +kal_u32 g_image_word = 0; // and was given this word +kal_uintptr g_entered = 0; // the task that entered the image + +unsigned home(kal_uintptr task) { + return static_cast((static_cast(task) * 0x9E3779B97F4A7C15ull) >> 40) % kLines; +} + +task_line* find(kal_uintptr task) { + const unsigned h = home(task); + for (unsigned k = 0; k < kReach; ++k) { + task_line& l = g_lines[(h + k) % kLines]; + if (__atomic_load_n(&l.task, __ATOMIC_ACQUIRE) == task) return &l; + } + return nullptr; +} + +task_line* take(kal_uintptr task) { + const unsigned h = home(task); + for (unsigned k = 0; k < kReach; ++k) { + task_line& l = g_lines[(h + k) % kLines]; + kal_uintptr none = 0; + if (__atomic_compare_exchange_n(&l.task, &none, task, false, __ATOMIC_ACQ_REL, __ATOMIC_RELAXED)) return &l; + } + return nullptr; +} + +// --- the record ---------------------------------------------------------------------------------- + +// A standard error whose reader has stopped reading would hold the record, and +// with it the program the request would have ended; a write is bounded where +// the implementation bounds one (openkal.timeout, a second), and what it cannot +// write in the bound is left unwritten. +void say(const char* s, kal_uintptr n) { + const kal_stream err = kal_stderr(); +#if OKRUN_HAS_TIMEOUT + if (kal_timeout_write(err, s, n, 1000000000ull) != -static_cast(kal_err_not_supported)) return; +#endif + kal_stream_write(err, s, n); +} + +char g_out[4096]; +kal_uintptr g_at = 0; +void flush() { if (g_at) say(g_out, g_at); g_at = 0; } +void put(const char* s) { + for (; *s; ++s) { + if (g_at == sizeof g_out) flush(); + g_out[g_at++] = *s; + } +} +void put_number(kal_u64 v) { + char d[24]; + int n = 0; + do { d[n++] = static_cast('0' + v % 10); v /= 10; } while (v); + char o[24]; + int k = 0; + while (n) o[k++] = d[--n]; + o[k] = 0; + put(o); +} + +void put_line(kal_uintptr task, unsigned long call, const binding* names, unsigned long count) { + put("okrun: task "); + put_number(task); + if (task == g_entered) put(" (main)"); + put(": "); + put(call && call <= count ? names[call - 1].name : "in no call that waits"); + put("\n"); +} + +void write_record() { + unsigned long count = 0; + const binding* names = bindings(count); + put("okrun: asked to end; the openkal call each task of the image waits in:\n"); + if (const task_line* m = find(g_entered)) put_line(g_entered, __atomic_load_n(&m->call, __ATOMIC_ACQUIRE), names, count); + for (const task_line& l : g_lines) { + const kal_uintptr task = __atomic_load_n(&l.task, __ATOMIC_ACQUIRE); + if (task && task != g_entered) put_line(task, __atomic_load_n(&l.call, __ATOMIC_ACQUIRE), names, count); + } + if (const unsigned n = __atomic_load_n(&g_unheld, __ATOMIC_ACQUIRE)) { + put("okrun: and "); + put_number(n); + put(" task(s) more, for which the record has no line\n"); + } + flush(); +} + +// --- the task that waits for the requests -------------------------------------------------------- + +// The requests, given to an image that took them over: each counted, zero +// skipped where the count wraps (openkal 0.25), and every task that waits upon +// the word woken. +void deliver(kal_u32 requests) { + kal_u32 next = __atomic_load_n(&g_image_word, __ATOMIC_RELAXED) + requests; + if (next == 0) next = 1; + __atomic_store_n(&g_image_word, next, __ATOMIC_RELEASE); + kal_task_wake(&g_image_word, 0x7fffffff, nullptr); +} + +void watch(void*) { + const kal_u32* word = kal_process_stop_requested(); + if (!word) { + __atomic_store_n(&g_watched, 0, __ATOMIC_RELEASE); + profile_note("requests", "not taken: the implementation reports no request to end", 0); + return; + } + profile_note("requests", "taken: a request writes the call each task waits in", 0); + kal_u32 seen = 0; + for (;;) { + const kal_u32 now = __atomic_load_n(word, __ATOMIC_ACQUIRE); + if (now == seen) { + // A wait that fails is tried again a little later, rather than at once and for ever. + if (kal_task_wait(word, now, 0) != kal_ok) kal_time_sleep(10000000ull); + continue; + } + const kal_u32 requests = now - seen; + seen = now; + write_record(); + if (__atomic_load_n(&g_taken, __ATOMIC_ACQUIRE)) { + deliver(requests); + continue; + } + kal_process_end_as_requested(); + // It returns only where the program has not been asked to end, and it has. + static const char why[] = "okrun: asked to end, and kal_process_end_as_requested returned"; + kal_abort(why, sizeof why - 1); + } +} + +} // namespace + +void watch_requests() { + g_entered = kal_task_current(); + take(g_entered); + __atomic_store_n(&g_watched, 1, __ATOMIC_RELEASE); + kal_task watcher{}; + if (kal_task_start(&watch, nullptr, &watcher) == kal_ok) return; + __atomic_store_n(&g_watched, 0, __ATOMIC_RELEASE); + profile_note("requests", "not taken: no task could be started to wait for them", 0); +} + +task_line* task_begin() { + if (!__atomic_load_n(&g_watched, __ATOMIC_ACQUIRE)) return nullptr; + if (task_line* l = take(kal_task_current())) return l; + __atomic_add_fetch(&g_unheld, 1u, __ATOMIC_RELAXED); + return &g_no_line; +} + +void task_end(task_line* line) { + if (line == &g_no_line) { + __atomic_sub_fetch(&g_unheld, 1u, __ATOMIC_RELAXED); + return; + } + if (!line) return; + __atomic_store_n(&line->call, 0ul, __ATOMIC_RELAXED); + __atomic_store_n(&line->task, kal_uintptr{0}, __ATOMIC_RELEASE); +} + +task_line* wait_begin(unsigned long index) { + if (!__atomic_load_n(&g_watched, __ATOMIC_RELAXED)) return nullptr; + task_line* l = find(kal_task_current()); + if (l) __atomic_store_n(&l->call, index + 1, __ATOMIC_RELEASE); + return l; +} + +void wait_end(task_line* line) { + if (line) __atomic_store_n(&line->call, 0ul, __ATOMIC_RELEASE); +} + +const kal_u32* requests_taken() { + // Taken now, as the image's own call would have taken them, whether or not + // the runner's task has yet; a request is then counted, and its record + // written, whichever asked first. + const kal_u32* word = kal_process_stop_requested(); + if (!word || !__atomic_load_n(&g_watched, __ATOMIC_ACQUIRE)) return word; + __atomic_store_n(&g_taken, 1, __ATOMIC_RELEASE); + return &g_image_word; +} + +#else + +// Without processes or contexts there is no task to wait for a request: an +// image that asks for the requests is given the implementation's word. +struct task_line {}; +void watch_requests() {} +task_line* task_begin() { return nullptr; } +void task_end(task_line*) {} +task_line* wait_begin(unsigned long) { return nullptr; } +void wait_end(task_line*) {} +#if OKRUN_HAS_PROCESS +const kal_u32* requests_taken() { return kal_process_stop_requested(); } +#endif + +#endif + +} // namespace okrun diff --git a/tools/tests/end_request.py b/tools/tests/end_request.py new file mode 100644 index 0000000..e92ddd6 --- /dev/null +++ b/tools/tests/end_request.py @@ -0,0 +1,81 @@ +"""A request to end names the openkal call each task of an image waits in (0.7.0). + +okrun runs examples/ending, whose main task joins another that waits upon a +word, and is asked to end (SIGTERM; on Windows CTRL_BREAK_EVENT to its process +group): its error stream names each task the image printed --- the main task in +kal_task_join, the other in kal_task_wait --- and the program ends as the +request would have ended it. With `takes' the image took the requests over: the +record names kal_task_wait and kal_time_sleep, and the image ends by itself with +its own status, 7.""" +import argparse +import os +from pathlib import Path +import re +import signal +import subprocess +import threading +import time + +parser = argparse.ArgumentParser(description=__doc__) +parser.add_argument('--okrun', required=True, type=Path) +parser.add_argument('--image', required=True, type=Path) +args = parser.parse_args() +windows = os.name == 'nt' +# What a request to end leaves of a program that did not take it over: the +# signal, or the status Windows records for a console interrupt +# (STATUS_CONTROL_C_EXIT). +ended_as_requested = 0xC000013A if windows else -signal.SIGTERM + + +def ask_to_end(*extra): + flags = subprocess.CREATE_NEW_PROCESS_GROUP if windows else 0 + child = subprocess.Popen([str(args.okrun), str(args.image), *extra], stdout=subprocess.PIPE, + stderr=subprocess.PIPE, creationflags=flags) + out, err = [], [] + said = threading.Event() + + def read_out(): + for line in child.stdout: + out.append(line.decode().replace('\r', '')) + said.set() + + def read_err(): + err.append(child.stderr.read().decode().replace('\r', '')) + + readers = [threading.Thread(target=f, daemon=True) for f in (read_out, read_err)] + for reader in readers: + reader.start() + if not said.wait(timeout=60): + child.kill() + raise AssertionError('the image said nothing in a minute') + tasks = re.fullmatch(r'ending: main (\d+), other (\d+)', out[0].strip()) + assert tasks, out[0] + # The other task has begun and the main task has said so: each is a moment + # from the call it waits in. + time.sleep(0.5) + child.send_signal(signal.CTRL_BREAK_EVENT if windows else signal.SIGTERM) + try: + status = child.wait(timeout=60) + except subprocess.TimeoutExpired: + child.kill() + raise AssertionError('asked to end, the program had not ended in a minute') + for reader in readers: + reader.join(timeout=10) + record = ''.join(err) + print(record, end='') + return status, tasks.group(1), tasks.group(2), ''.join(out), record + + +status, main, other, out, err = ask_to_end() +assert 'okrun: asked to end; the openkal call each task of the image waits in:' in err, err +assert f'okrun: task {main} (main): kal_task_join' in err, err +assert f'okrun: task {other}: kal_task_wait' in err, err +assert status == ended_as_requested, (status, ended_as_requested) +print(f' ok asked to end, the record names the call of each task, and the program ended as asked ({status})') + +status, main, other, out, err = ask_to_end('takes') +assert f'okrun: task {main} (main): kal_task_wait' in err, err +assert f'okrun: task {other}: kal_time_sleep' in err, err +assert 'ending: asked to end, and the image ends by itself' in out, out +assert status == 7, status +print(' ok an image that took the requests over is named the same, and ends by itself (7)') From 1b7159f44782a0ecc6d9b83d5f75e115ad8942ad Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Thu, 19 Nov 2026 15:44:57 +0900 Subject: [PATCH 2/2] 0.7.0: the runner follows the openkal 0.26 family openkal ^0.26.0 and, as the defaults per system, openkal-linux ^0.27.0, openkal-macos ^0.24.0, openkal-windows ^0.23.0 and openkal-freebsd ^0.2.0. The bound names are generated from SURFACE.txt, so 0.26 needs no change of the runner's sources. Every member is 0.7.0: openkal-ld, openkal-run, openkal-tools and openkal-bind. CI compiles the process-unit image against the 0.26 declarations the tools resolved. A published release builds its programs over openkal-platform 0.31.0, whose version group holds this family, with mcpp 2026.11.18.1 (the platform's floor is 2026.11.17.1). --- .github/workflows/ci.yml | 4 ++-- .github/workflows/release-binaries.yml | 12 +++++++----- README.md | 9 +++++++++ bind/mcpp.toml | 2 +- ld/mcpp.toml | 2 +- run/mcpp.toml | 12 ++++++------ tools/mcpp.toml | 2 +- 7 files changed, 27 insertions(+), 16 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3456a0b..b0243ac 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,8 +81,8 @@ jobs: bash examples/build-image.sh "$arch" "out/$arch/hello.oke" examples/hello/app.c # The declarations are compiled from the public specification the # tools resolved: any patch of its minor version (openkal clause 8), - # which is 0.25.1 since that patch was published. - spec=$(find "$HOME/.mcpp" -path '*openkal*0.25.*/include/openkal/process.h' -type f | sort -V | tail -1) + # 0.26 since 0.7.0. + spec=$(find "$HOME/.mcpp" -path '*openkal*0.26.*/include/openkal/process.h' -type f | sort -V | tail -1) test -n "$spec" CPATH="${spec%/openkal/process.h}" bash examples/build-image.sh "$arch" "out/$arch/process-unit.oke" examples/process-unit/app.c bash examples/build-image.sh "$arch" "out/$arch/liboktwice.okso" examples/needed/lib.c diff --git a/.github/workflows/release-binaries.yml b/.github/workflows/release-binaries.yml index 2698d3f..5997fd4 100644 --- a/.github/workflows/release-binaries.yml +++ b/.github/workflows/release-binaries.yml @@ -18,7 +18,7 @@ on: description: "The release tag the binaries are built from and attached to (e.g. 0.1.3)" required: true platform: - description: "The openkal-platform whose hosted arrangement builds the tools: the one whose version group holds the implementations the tag pins (0.1.5: 0.19.0; 0.1.6: 0.19.1; 0.1.7: 0.19.2; 0.1.8: 0.20.0; 0.1.9: 0.20.1; 0.3.0: 0.21.0; 0.3.1: 0.21.1; 0.4.2: 0.23.1; 0.4.3 and 0.4.4: 0.23.3)" + description: "The openkal-platform whose hosted arrangement builds the tools: the one whose version group holds the implementations the tag pins (0.1.5: 0.19.0; 0.1.6: 0.19.1; 0.1.7: 0.19.2; 0.1.8: 0.20.0; 0.1.9: 0.20.1; 0.3.0: 0.21.0; 0.3.1: 0.21.1; 0.4.2: 0.23.1; 0.4.3 and 0.4.4: 0.23.3; 0.7.0: 0.31.0)" required: true default: "0.21.0" asset_revision: @@ -40,16 +40,18 @@ env: # 2026.11.10.1: openkal-run binds the interfaces its implementation provides. # mcpp_ref supplies the candidate until this release is installable. # 2026.11.15.1: openkal-platform 0.28.0, the default platform below, requires - # 2026.11.14.1 or later. - MCPP_VERSION: 2026.11.15.1 + # 2026.11.14.1 or later. 2026.11.18.1 (0.7.0): openkal-platform 0.31.0 + # requires 2026.11.17.1 or later, and its CI runs 2026.11.18.1. + MCPP_VERSION: 2026.11.18.1 # The platform whose hosted arrangement the programs are built over, named by # the dispatch beside the tag: a tag's tools pin exact implementations, and the # platform is the one whose version group holds them (0.1.4: 0.18.0; 0.1.5: # 0.19.0, openkal-linux 0.19.0; 0.1.6: 0.19.1; 0.1.7: 0.19.2; 0.1.8: 0.20.0; 0.1.9: 0.20.1; - # 0.3.0: 0.21.0; 0.3.1: 0.21.1; 0.4.2: 0.23.1; 0.4.3 and 0.4.4: 0.23.3). + # 0.3.0: 0.21.0; 0.3.1: 0.21.1; 0.4.2: 0.23.1; 0.4.3 and 0.4.4: 0.23.3; + # 0.7.0, the openkal 0.26 family: 0.31.0). # A published release builds over the platform named here, which a release # that changes the pinned implementations updates in the same commit. - PLATFORM_VERSION: ${{ github.event.inputs.platform || '0.28.0' }} + PLATFORM_VERSION: ${{ github.event.inputs.platform || '0.31.0' }} XLINGS_VERSION: v2026.10.26.1 XLINGS_NON_INTERACTIVE: '1' diff --git a/README.md b/README.md index 936d7c3..45df945 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,15 @@ release carries its binaries (0.6.3 was published without them), and it adds FreeBSD x86_64 and aarch64: static programs of the platform's hosted musl identity, built on Linux and run in a FreeBSD machine before they are attached. +Version 0.7.0 writes, when the program is asked to end, the openkal call each +task of the image waits in, with the task's identity, and then acts on the +request as before ([When the program is asked to end](#when-the-program-is-asked-to-end)). +The package follows openkal 0.26: openkal `^0.26.0` and, as the defaults per +system, openkal-linux `^0.27.0`, openkal-macos `^0.24.0`, openkal-windows +`^0.23.0` and openkal-freebsd `^0.2.0`. The names the runner binds are generated +from the specification's SURFACE.txt, as before. A release's programs are built +over openkal-platform 0.31.0, whose version group holds this family. + ## An image ```sh diff --git a/bind/mcpp.toml b/bind/mcpp.toml index 7e72126..cee1f61 100644 --- a/bind/mcpp.toml +++ b/bind/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "openkal-bind" -version = "0.6.4" +version = "0.7.0" # `mcpp::xpkg_request', `mcpp::decision' (protocol 15). mcpp = ">=2026.10.1.3" description = "A build plugin: a library published as an ok image (.okso) and a C header is called from a program of any system, through a binding generated from the header and libokrun." diff --git a/ld/mcpp.toml b/ld/mcpp.toml index 3e7ab94..d08d6a9 100644 --- a/ld/mcpp.toml +++ b/ld/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "openkal-ld" -version = "0.6.4" +version = "0.7.0" description = "libokld: the ok format (openkal image format) --- its definition, a reader of bytes, a checker, a signer, and a loader. Freestanding: no C library, no exceptions." license = "Apache-2.0" authors = ["mcpplibs"] diff --git a/run/mcpp.toml b/run/mcpp.toml index 404961a..2fdf2f5 100644 --- a/run/mcpp.toml +++ b/run/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "openkal-run" -version = "0.6.4" +version = "0.7.0" description = "libokrun: the runner's core --- an ok image's names bound to this process's one openkal implementation, in the image's calling convention, and its entry entered." license = "Apache-2.0" authors = ["mcpplibs"] @@ -19,14 +19,14 @@ requires = ["mcpp:kernel-abi=openkal"] kind = "lib" [dependencies] -openkal = "^0.25.0" +openkal = "^0.26.0" openkal-ld = { path = "../ld" } [defaults."mcpp:kernel-abi=openkal"] -linux = "openkal-linux@^0.26.0" -macos = "openkal-macos@^0.23.0" -windows = "openkal-windows@^0.21.0" -'cfg(os = "freebsd")' = "openkal-freebsd@^0.1.0" +linux = "openkal-linux@^0.27.0" +macos = "openkal-macos@^0.24.0" +windows = "openkal-windows@^0.23.0" +'cfg(os = "freebsd")' = "openkal-freebsd@^0.2.0" # THE INTERFACES THE RUNNER ITSELF CALLS (0.6; 0.6.3 the core runner): an implementation that does # not provide one of them is refused when the graph is resolved. Every other interface is bound diff --git a/tools/mcpp.toml b/tools/mcpp.toml index e93a0cc..7da8573 100644 --- a/tools/mcpp.toml +++ b/tools/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "openkal-tools" -version = "0.6.4" +version = "0.7.0" description = "okrun, which runs an ok image on this system, and okld, the format's tool on a build machine (check, note, sign, inspect)." license = "Apache-2.0" authors = ["mcpplibs"]