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);