Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<P>(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<T>` |
| `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` |
Expand Down
12 changes: 6 additions & 6 deletions mcpp.toml
Original file line number Diff line number Diff line change
@@ -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"]
Expand All @@ -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 `<arch>-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"
Expand Down
8 changes: 8 additions & 0 deletions src/env.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<unsigned>(v >> 32), static_cast<unsigned>((v >> 16) & 0xffffu),
static_cast<unsigned>(v & 0xffffu) };
}

namespace {
// A value of a counting operation: the length it has, then the bytes.
template <class F>
Expand Down
11 changes: 11 additions & 0 deletions src/env.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -64,4 +64,15 @@ std::vector<std::filesystem::path> search_path();
std::optional<std::filesystem::path> find_executable(std::string_view name);
std::optional<std::filesystem::path> 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
13 changes: 13 additions & 0 deletions src/process.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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> owned_unit::create() {
auto s = std::make_shared<state>();
std::string reference(512, '\0'); kal_uintptr used = 0;
Expand Down Expand Up @@ -426,6 +429,16 @@ result<process> 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;
Expand Down
15 changes: 15 additions & 0 deletions src/process.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -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<unit_observer> open(std::string_view reference);
unit_observer() = default;
unit_observer(unit_observer&&) noexcept;
Expand Down Expand Up @@ -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<process> spawn(const spawn_options& options);

process();
Expand Down
6 changes: 6 additions & 0 deletions tests/facts_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,12 @@ void check_effective_user(std::integral_constant<os::platform, P>, 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<os::platform::linux>([&](auto p) {
Expand Down
44 changes: 43 additions & 1 deletion tests/process_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<std::string> 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<std::string>& 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<std::string> 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();
Expand Down Expand Up @@ -425,6 +438,35 @@ UTest process_tests{"process", [] {
static_cast<long long>(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.
Expand Down
8 changes: 8 additions & 0 deletions tests/unit_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,14 @@ child helper_child{"helper", [](std::vector<std::string> 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);
Expand Down
Loading