diff --git a/CHANGELOG.md b/CHANGELOG.md index 087538b..e2576e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,32 @@ # Changelog +## 0.4.5 + +- **A start refused for its size says so.** Where the system refuses a start + for the size of what it was given, `process::spawn` reports `errc::no_space`, + and the error's context states the number and the bytes of the arguments and + of the variables (openkal 0.26, clause 7.6). An implementation of the 0.26 + family keeps no bound of its own, so two thousand arguments or variables + reach a started program wherever the system admits them; under the 0.25 + family a start of more than 512 of either was reported as out of memory. +- **Whether a unit can be declared is a property (`process::units_observable`).** + False where the system gives a program nothing to make a reference from; + `owned_unit::create` is then `errc::not_supported`, and a caller learns it + before it starts anything. `unit_observer::open` reports + `errc::not_supported` for a unit the program can never observe --- a + reference made in another process space, or a unit whose identity the system + did not keep once its last holder was lost --- an answer that does not change + by waiting, where `unit_state::unknown` and any other error may pass (openkal + 0.26, clause 7.18). +- **The kernel layer's version (`env::kernel_layer`).** The version of openkal's + specification the implementation beneath the program answers for, as + `layer_version{major, minor, patch}`: what a report states beside the system. +- **openkal 0.26 and the implementations of its family are admitted.** openkal + `>=0.24.0, <0.27.0`, openkal-linux `>=0.25.0, <0.28.0`, openkal-macos + `>=0.22.0, <0.25.0`, openkal-windows `>=0.20.0, <0.24.0` (0.22 and 0.23), + openkal-emscripten `>=0.13.0, <0.16.0`. A graph that holds an earlier family + builds as before. + ## 0.4.4 - **The system's object models: `windows::com` and `macos::objc`.** A system's diff --git a/README.md b/README.md index 9faa192..92d5ca5 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,12 @@ An observer opens that opaque reference and reports `unit_state::occupied`, `empty` or `unknown`. Its type exposes neither admission nor termination. Closing it terminates nothing. Missing native identity, including loss of all native reference holders on a system that requires them, remains `unknown`. +`process::units_observable()` answers whether a unit can be declared where the +program runs. `unit_observer::open` reports `errc::not_supported` for a unit +this program can never observe --- a reference made in another process space, +or a unit whose identity the system did not keep once its last holder was +lost: that answer does not change by waiting, where `unknown` may (0.4.5, +openkal 0.26). `owned_unit::retire(continuation)` seals admission before observing the end of external members. The continuation identifies the surviving supervising @@ -108,7 +114,7 @@ dropped (0.2.8). |---|---| | `mcpplibs.os.platform` | `PLATFORM`, `ARCH`, `is_linux` / `is_macos` / `is_windows` / `is_posix` / `is_openkal` / `is_emscripten`, `exe_suffix`, `path_list_separator`; `host()`, a constant expression on a native target; `can_run_on(p)` and `on

(f)`, a platform question that holds in a native build and an image alike | | `mcpplibs.os.error` | `errc` (openkal's closed set of conditions), `error`, `result` | -| `mcpplibs.os.env` | variables (names without case on Windows), `NAME=value` entries as overrides (`assignments`), arguments, the program's own image, lists of directories in the host's separator (`split_list`, `join_list`), PATH search with PATHEXT | +| `mcpplibs.os.env` | variables (names without case on Windows), `NAME=value` entries as overrides (`assignments`), arguments, the program's own image, lists of directories in the host's separator (`split_list`, `join_list`), PATH search with PATHEXT, the kernel layer's version (`kernel_layer`) | | `mcpplibs.os.fs` | `write_atomic`, `publish` (no replace), `append`, `sync`, `caps`, `lock`, links, `set_executable`, `stamp_of`, `identity_of`, `owner_of`, `writable`, `locate`, `absolute`, `names_a_place`, `canonical`, a bounded `read`; what a volume does, measured (`measure`, `volume_type`), and the operations that follow it (`place`, `exchange`); names in the host's rules without the file system: `generic`, `native`, `extended`, `is_absolute`, `same`, `within`; which names changed (`watcher`: inotify, kqueue, `ReadDirectoryChangesW`; a look when asked in an image and on Emscripten) | | `mcpplibs.os.process` | `spawn`, `run` (and with bounds: a hard bound, a grace, a drain, output limits), `exec`, a command line joined as it is for the command interpreter (`one_string`), pipes, both outputs on one pipe, output onto this program's error output, units and `end_unit`, declared units, observation and retirement, bound lifetime, bounded waits and reads; `self`, `describe`, `alive`, `threads` | | `mcpplibs.os.interrupt` | `requested`, `wait`, `end_as_requested`, `end_as_output_closed` | diff --git a/mcpp.toml b/mcpp.toml index 38a4f67..a31b563 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -1,7 +1,7 @@ [package] namespace = "mcpplibs" name = "os" -version = "0.4.4" +version = "0.4.5" description = "mcpplibs.os: a C++ operating-system library over openkal --- processes, files, environment, terminals, directories and local IPC, with compile-time platform constants and a few platform modules." license = "Apache-2.0" authors = ["mcpplibs"] @@ -12,23 +12,23 @@ repo = "https://github.com/mcpplibs/os" # own C and C++ runtime. A program that wants the standalone arrangement, or # the image arrangement of `-openkal`, selects it in its own manifest. [dependencies] -openkal = ">=0.24.0, <0.26.0" +openkal = ">=0.24.0, <0.27.0" [target.linux.dependencies] -openkal-linux = ">=0.25.0, <0.27.0" +openkal-linux = ">=0.25.0, <0.28.0" [target.macos.dependencies] -openkal-macos = ">=0.22.0, <0.24.0" +openkal-macos = ">=0.22.0, <0.25.0" [target.windows.dependencies] -openkal-windows = ">=0.20.0, <0.22.0" +openkal-windows = ">=0.20.0, <0.24.0" # Emscripten (`wasm32-emscripten`): openkal written above the C library, with # twelve of openkal's fifteen interfaces. `openkal.process', `openkal.exec' and # `openkal.space' are absent, so a program that starts one fails at link # naming the symbol; `openkal.task' is present in a `-pthread' link only. [target.'cfg(os = "emscripten")'.dependencies] -openkal-emscripten = ">=0.13.0, <0.15.0" +openkal-emscripten = ">=0.13.0, <0.16.0" [targets.os] kind = "lib" diff --git a/src/env.cpp b/src/env.cpp index 5153360..cce4f64 100644 --- a/src/env.cpp +++ b/src/env.cpp @@ -3,12 +3,20 @@ module mcpplibs.os.env; import std; import openkal.types; import openkal.env; +import openkal.version; import openkal.fs; import mcpplibs.os.platform; import mcpplibs.os.fs; namespace mcpplibs::os::env { +// openkal encodes a version as major << 32 | minor << 16 | patch. +layer_version kernel_layer() noexcept { + const auto v = kal_version(); + return { static_cast(v >> 32), static_cast((v >> 16) & 0xffffu), + static_cast(v & 0xffffu) }; +} + namespace { // A value of a counting operation: the length it has, then the bytes. template diff --git a/src/env.cppm b/src/env.cppm index 660555f..2a90b6e 100644 --- a/src/env.cppm +++ b/src/env.cppm @@ -64,4 +64,15 @@ std::vector search_path(); std::optional find_executable(std::string_view name); std::optional find_executable(std::string_view name, std::string_view path_list); + +// THE KERNEL LAYER BENEATH THIS PROGRAM (0.4.5): the version of openkal's +// specification its implementation answers for. What a report of a failure +// states beside the system, and what tells two families of the layer apart +// where this library admits both. +struct layer_version { + unsigned major = 0, minor = 0, patch = 0; + auto operator<=>(const layer_version&) const = default; +}; +layer_version kernel_layer() noexcept; + } // namespace mcpplibs::os::env diff --git a/src/process.cpp b/src/process.cpp index 35699b8..e39d092 100644 --- a/src/process.cpp +++ b/src/process.cpp @@ -138,6 +138,9 @@ owned_unit::owned_unit() = default; owned_unit::owned_unit(owned_unit&&) noexcept = default; owned_unit& owned_unit::operator=(owned_unit&&) noexcept = default; owned_unit::~owned_unit() = default; +bool units_observable() noexcept { + return (kal_process_props() & kal::process::job_observe.bits) != 0; +} result owned_unit::create() { auto s = std::make_shared(); std::string reference(512, '\0'); kal_uintptr used = 0; @@ -426,6 +429,16 @@ result process::spawn(const spawn_options& o) { if (n.file.h) kal_fs_close_file(n.file); else if (n.channel && n.child.h) kal_process_channel_close(n.child); } + if (rc == kal_err_no_space) { + // The system refused the start for the size of what it was given + // (openkal 0.26, clause 7.6); the two sizes are what a caller acts upon. + std::size_t argument_bytes = 0, variable_bytes = 0; + for (const auto n : argv_lens) argument_bytes += n; + for (const auto n : envp_lens) variable_bytes += n; + return fail_streams(from_kal(rc, std::format( + "starting {} with {} arguments of {} bytes and {} variables of {} bytes", + fs::generic_utf8(program), argv.size(), argument_bytes, envp.size(), variable_bytes))); + } if (rc != kal_ok) return fail_streams(from_kal(rc, std::format("starting {}", fs::generic_utf8(program)))); if (unit) { s->job = job; s->has_job = true; } process p; diff --git a/src/process.cppm b/src/process.cppm index 5347a8c..ccc4c35 100644 --- a/src/process.cppm +++ b/src/process.cppm @@ -56,8 +56,20 @@ struct program { enum class unit_state { unknown, occupied, empty }; class process; +// Whether a unit can be declared here: false where the system gives this +// program nothing to make a reference from, and `owned_unit::create' is then +// errc::not_supported. A property of where the program runs, asked before +// anything is started (0.4.5, openkal 0.26). +bool units_observable() noexcept; + class unit_observer { public: + // errc::not_supported: this program can never observe the unit --- the + // reference was made in another process space of this start of the + // system, or the system did not keep the unit's identity once its last + // holder was lost --- and the answer is the same however long the caller + // waits. Any other error, and `unit_state::unknown', may pass (0.4.5, + // openkal 0.26). static result open(std::string_view reference); unit_observer() = default; unit_observer(unit_observer&&) noexcept; @@ -150,6 +162,9 @@ struct exit_status { class process { public: + // errc::no_space: the system refused the start for the size of its + // arguments and variables, and the error's context states the number and + // the bytes of each (0.4.5, openkal 0.26). static result spawn(const spawn_options& options); process(); diff --git a/tests/facts_test.cpp b/tests/facts_test.cpp index 635de49..6fb341c 100644 --- a/tests/facts_test.cpp +++ b/tests/facts_test.cpp @@ -29,6 +29,12 @@ void check_effective_user(std::integral_constant, const char* s } UTest facts_tests{"facts", [] { + { + // The layer beneath this program answers for a version of openkal's specification. + const auto layer = mcpplibs::os::env::kernel_layer(); + expect(layer >= mcpplibs::os::env::layer_version{0, 24, 0} && layer.major == 0) + << "the kernel layer states its version: " << layer.major << "." << layer.minor << "." << layer.patch; + } const bool ci = os::env::get("GITHUB_ACTIONS").has_value(); int asked = 0; os::on([&](auto p) { diff --git a/tests/process_test.cpp b/tests/process_test.cpp index 7b9c853..dcebdcf 100644 --- a/tests/process_test.cpp +++ b/tests/process_test.cpp @@ -181,7 +181,20 @@ int run_errand(std::string_view errand) { } // A copy of this program started with an errand does it, and runs no case. -child errand_child{"errand", [](std::vector args) { return args.size() == 1 ? run_errand(args[0]) : 98; }}; +// `count': how many arguments followed the errand and how many of the test's +// variables this program holds. +int count_vectors(const std::vector& args) { + std::size_t variables = 0; + for (int i = 0; i < 2000; ++i) + if (os::env::get(std::format("OS_TEST_V{:04}", i)).value_or("").size() == 100) ++variables; + (void)os::stdio::write_output(std::format("{} {}", args.size() - 1, variables)); + return 0; +} + +child errand_child{"errand", [](std::vector args) { + if (!args.empty() && args[0] == "count") return count_vectors(args); + return args.size() == 1 ? run_errand(args[0]) : 98; +}}; UTest process_tests{"process", [] { const auto self = os::env::image(); @@ -425,6 +438,35 @@ UTest process_tests{"process", [] { static_cast(theirs->user.count())); expect(u && (counted || untold)) << "a waited-for child's processor time and memory are accounted to its parent"; } + if (os::env::kernel_layer() >= os::env::layer_version{0, 26, 0}) { + // A start is bounded by the system alone (openkal 0.26, clause 7.6): + // what is given reaches the program, or the system's refusal for its + // size is errc::no_space and states both sizes. This package admits + // the 0.25 family too, whose implementations bound a start at 512 + // entries or read at most 512 variables; under it nothing is asserted. + auto o = copy("count"); + o.out = os::process::stdio::pipe; + for (int i = 0; i < 2000; ++i) o.args.push_back("a"); + for (int i = 0; i < 2000; ++i) o.env.emplace_back(std::format("OS_TEST_V{:04}", i), std::string(100, 'x')); + const auto all = os::process::run(o); + const auto stated = [](const os::error& e) { + return e.code == os::errc::no_space && e.context.find(" arguments of ") != std::string::npos + && e.context.find(" variables of ") != std::string::npos; + }; + if (!all) std::printf(" (two thousand arguments and variables: %s)\n", all.error().message().c_str()); + else if (all->out != "2000 2000") std::printf(" (the copy counted `%s', status %d)\n", all->out.c_str(), all->status.code); + expect(all ? all->out == "2000 2000" : stated(all.error())) + << "two thousand arguments and two thousand variables reach a started program, or the refusal states their sizes"; + auto large = copy("count"); + large.args.push_back(std::string(std::size_t{1} << 20, 'b')); + const auto one = os::process::run(large); + if (!one) std::printf(" (an argument of one mebibyte: %s)\n", one.error().message().c_str()); + expect(one ? one->out == "1 0" : stated(one.error())) + << "an argument of one mebibyte reaches a started program, or the refusal states its size"; + } else { + const auto layer = os::env::kernel_layer(); + std::printf(" (the kernel layer is openkal %u.%u.%u: a start's bound is its 0.26)\n", layer.major, layer.minor, layer.patch); + } { // The command interpreter given a command with quotation marks, joined // as it is; refused where a program receives a vector. diff --git a/tests/unit_test.cpp b/tests/unit_test.cpp index fff37c3..c5eccdc 100644 --- a/tests/unit_test.cpp +++ b/tests/unit_test.cpp @@ -88,6 +88,14 @@ child helper_child{"helper", [](std::vector args) -> int { }}; UTest unit_tests{"unit", [] { + // Asked before anything is started; where it is false, declaring a unit is + // refused, and this program is left outside any unit. + if (!process::units_observable()) { + const auto refused = process::owned_unit::create(); + expect(!refused && refused.error().code == mcpplibs::os::errc::not_supported) + << "a unit is not declared where the system gives nothing to make a reference from"; + return; + } const auto identity = process::self(); expect(fatal(identity.has_value())) << "this program names itself"; const auto root = std::filesystem::temp_directory_path() / std::format("os-unit-{}",identity->id);