Skip to content
Open
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
28 changes: 25 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,37 @@ An implementation of [openkal](https://github.com/mcpplibs/openkal) for Windows.

```toml
[dependencies]
openkal = "0.25.0"
openkal = "0.26.0"

[target.'cfg(windows)'.dependencies]
openkal-windows = "0.22.2"
openkal-windows = "0.23.0"
```

Its purpose is as much to test the specification as to be used. openkal was
drawn against systems that share an ancestry; a third implementation on a system
that shares none of it is what turns "this interface is not Unix's shape" from a
claim into an observation.

## What 0.23 changes (openkal 0.26)

**A unit's reference names its boot and its session** (clause 7.18). A unit is a
named job in the session's namespace, and its reference (`W2`) adds the count of
boots the system's loader keeps and the session. A reference of another boot is
`empty`. A reference of another session, and one whose name the system no longer
keeps --- it drops a job's name with its last handle, whether or not a member
remains --- are refused by `kal_process_job_open` with `kal_err_not_supported`:
neither can be opened however long the caller waits, where both were a name that
is not there. A reference in the earlier form (`W1`) is answered by its name as
before. `KAL_PROCESS_PROP_JOB_OBSERVE` is claimed where the session can be read
and two handles compared. `tests/a_unit_reference_names_its_boot_and_session.cpp`.

**A start is bounded by the system alone** (clause 7.6). A started program read
its arguments and variables into fixed tables --- 256 arguments, 512 variables,
64 KiB of text --- and what did not fit was left out without a report: a program
given two thousand arguments counted 255. Both vectors are measured and held in
allocations of their size. A command line beyond the 32,767 units the system
takes is `kal_err_no_space`, as before.

## What 0.22.2 corrects

The manifest declares `openkal = "^0.25.0"`. An implementation written against a
Expand Down Expand Up @@ -79,7 +99,9 @@ when the count wraps.

The process interface provides the OpenKal 0.24 declared-unit operations.
Observation retains the original named-job handle and queries its active
membership. A missing name after every handle is lost reports `unknown`.
membership. A name the system dropped with its last handle is refused by
`kal_process_job_open` with `kal_err_not_supported` (0.23.0): it is not evidence
that the members have ended, and it cannot be opened again.
Retirement checks the live continuation identity and requires that no external
member remains. Closing an observation handle does not terminate the unit.

Expand Down
4 changes: 2 additions & 2 deletions mcpp.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
namespace = "mcpplibs"
name = "openkal-windows"
version = "0.22.2"
version = "0.23.0"
description = "An implementation of openkal for Windows, written on the Win32 interfaces and the object manager beneath them, using no C runtime symbol."
license = "Apache-2.0"

Expand Down Expand Up @@ -67,7 +67,7 @@ provides-interfaces = [

[dependencies]
# Every patch release of the specification's minor version (openkal clause 8).
openkal = "^0.25.0"
openkal = "^0.26.0"

# The package contributes definitions and no modules. The interface it
# implements is declared by the specification package, which this package
Expand Down
75 changes: 56 additions & 19 deletions src/env.cpp
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
#include "win.h"
#include <openkal/env.h>
#include <openkal/memory.h> // the tables are sized by what the environment holds

// The parameters a program receives at inception.
//
Expand All @@ -14,30 +15,33 @@
namespace {


constexpr int kMaxArgs = 256;
constexpr int kMaxVars = 512;
constexpr okw_uptr kText = 1u << 16;
// SIZED BY WHAT THE ENVIRONMENT HOLDS (0.23.0; openkal 0.26, clause 7.6).
// The tables were fixed --- 256 arguments, 512 variables, 64 KiB of text ---
// and what did not fit was left out without a word: a program started with
// two thousand arguments counted 255. A start is bounded by the environment
// alone, and that holds of what a program reads as much as of what its starter
// passes. Both vectors are measured, then held in one allocation each.
char* g_text = nullptr;
okw_uptr g_cap = 0;
okw_uptr g_used = 0;

char g_text[kText];
okw_uptr g_used = 0;
const char** g_argv = nullptr;
okw_uptr* g_argv_len = nullptr;
int g_argc = 0;

const char* g_argv[kMaxArgs];
okw_uptr g_argv_len[kMaxArgs];
int g_argc = 0;

const char* g_entry[kMaxVars]; // "name=value", as the environment states it
okw_uptr g_name_len[kMaxVars];
const char* g_value[kMaxVars];
okw_uptr g_value_len[kMaxVars];
int g_varc = 0;
const char** g_entry = nullptr; // "name=value", as the environment states it
okw_uptr* g_name_len = nullptr;
const char** g_value = nullptr;
okw_uptr* g_value_len = nullptr;
int g_varc = 0;

bool g_ready = false;

// Arguments and named values are stored as they were given: neither is a name.
const char* store(const wchar_t* w, int wlen, okw_uptr& out_len) {
if (g_used + 4 >= kText) { out_len = 0; return ""; }
if (g_used + 4 >= g_cap) { out_len = 0; return ""; }
char* at = g_text + g_used;
const okw_uptr n = okw::narrow(w, static_cast<okw_uptr>(wlen), at, kText - g_used, false);
const okw_uptr n = okw::narrow(w, static_cast<okw_uptr>(wlen), at, g_cap - g_used, false);
g_used += n + 1;
out_len = n;
return at;
Expand Down Expand Up @@ -69,8 +73,42 @@ void prepare() {
void fill() {
int count = 0;
wchar_t** parts = CommandLineToArgvW(GetCommandLineW(), &count);
wchar_t* block = GetEnvironmentStringsW();

// Measured first: the elements of each vector, and the units of both. A
// unit of this system's encoding is at most three bytes of the caller's.
okw_uptr units = 0;
int variables = 0;
if (!parts) count = 0;
for (int i = 0; i < count; ++i) units += static_cast<okw_uptr>(wide_length(parts[i])) + 1;
for (const wchar_t* p = block; p && *p; ) {
const int len = wide_length(p);
if (p[0] != L'=') { ++variables; units += static_cast<okw_uptr>(len) + 1; }
p += len + 1;
}
const okw_uptr slots = static_cast<okw_uptr>(count) + 1;
const okw_uptr vars = static_cast<okw_uptr>(variables) + 1;
g_cap = 3 * units + 8;
g_text = static_cast<char*>(kal_alloc(g_cap, 1));
g_argv = static_cast<const char**>(kal_alloc(slots * sizeof(char*), alignof(char*)));
g_argv_len = static_cast<okw_uptr*>(kal_alloc(slots * sizeof(okw_uptr), alignof(okw_uptr)));
g_entry = static_cast<const char**>(kal_alloc(vars * sizeof(char*), alignof(char*)));
g_name_len = static_cast<okw_uptr*>(kal_alloc(vars * sizeof(okw_uptr), alignof(okw_uptr)));
g_value = static_cast<const char**>(kal_alloc(vars * sizeof(char*), alignof(char*)));
g_value_len = static_cast<okw_uptr*>(kal_alloc(vars * sizeof(okw_uptr), alignof(okw_uptr)));
// Without memory for them there is nothing to answer from: no argument but
// the empty first one, and no variable.
static const char* none[1] = { "" };
static okw_uptr none_len[1] = { 0 };
if (!g_text || !g_argv || !g_argv_len || !g_entry || !g_name_len || !g_value || !g_value_len) {
if (parts) LocalFree(parts);
if (block) FreeEnvironmentStringsW(block);
g_argv = none; g_argv_len = none_len; g_argc = 1; g_varc = 0;
return;
}

if (parts) {
for (int i = 0; i < count && g_argc < kMaxArgs - 1; ++i) {
for (int i = 0; i < count; ++i) {
okw_uptr len = 0;
// AS GIVEN, AND UNTIL 0.7.3 EVERY BACKSLASH CAME OUT AS A SLASH.
// An argument is not a name: `C:\dir' and a pattern's `\d' are what
Expand All @@ -88,9 +126,8 @@ void fill() {
g_argv[0] = ""; g_argv_len[0] = 0; g_argc = 1;
}

wchar_t* block = GetEnvironmentStringsW();
if (block) {
for (wchar_t* p = block; *p && g_varc < kMaxVars; ) {
for (wchar_t* p = block; *p && g_varc < variables; ) {
const int len = wide_length(p);
// A name beginning with a separator is this environment's own
// bookkeeping and is not a variable a program set.
Expand Down
71 changes: 62 additions & 9 deletions src/process.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -1308,10 +1308,41 @@ using compare_objects_fn = BOOL (OKW_API*)(HANDLE,HANDLE);
compare_objects_fn unit_compare() {
return reinterpret_cast<compare_objects_fn>(okw::system_function(L"kernelbase.dll","CompareObjectHandles"));
}
bool observable_units() { return unit_compare() != nullptr; }
// WHAT A REFERENCE NAMES, AND WHAT AN OBSERVATION CAN ESTABLISH (openkal 0.26,
// clause 7.18). A unit is a named job in the session's own namespace
// (`Local\'), so a reference (`W2') names the count of boots and the session
// beside the job's name:
// another boot every program of it has ended EMPTY
// another session its names cannot be opened from here: `open'
// refuses, to this caller always
// this session, no such name
// the system drops a job's name with its last
// handle, whether or not a member remains, so the
// unit can never be opened again: `open' refuses
// this session, the job its count of active processes
// A `W1' reference names neither, and is answered by its name alone.
//
// The count of boots is the word the system's loader advances at each boot
// (KUSER_SHARED_DATA.BootId, at one address in every process). A resume from
// hibernation restores the word with the rest of memory, so it changes only
// where every program has ended. Zero where the word is not kept: the
// reference then names no boot, and none is compared.
kal_u64 unit_boot() { return *reinterpret_cast<const volatile unsigned*>(static_cast<okw_uptr>(0x7ffe02c4u)); }
bool unit_session(kal_u64& session) {
DWORD value = 0;
if (!ProcessIdToSessionId(GetCurrentProcessId(),&value)) return false;
session = value; return true;
}
// Claimed where a reference can be made: the session read, the handles compared.
bool observable_units() { kal_u64 session = 0; return unit_compare() != nullptr && unit_session(session); }
struct unit_identity {
kal_u64 owner = 0, birth = 0; char name[96]{};
kal_u64 owner = 0, birth = 0, boot = 0, session = 0; char name[96]{};
bool exact = false; // a W2 reference, which names its boot and its session
};
bool unit_earlier_boot(const unit_identity& u) {
const kal_u64 boot = unit_boot();
return u.exact && u.boot != 0 && boot != 0 && u.boot != boot;
}
bool unit_birth(kal_u64& birth) {
FILETIME created{}, ended{}, kernel{}, user{};
if (!GetProcessTimes(GetCurrentProcess(),&created,&ended,&kernel,&user)) return false;
Expand All @@ -1321,9 +1352,13 @@ bool unit_birth(kal_u64& birth) {
bool unit_parse(const char* p, kal_uintptr n, unit_identity& u) {
if (!p || n == 0 || n > 256) return false;
unit_reference::reader r{p,n}; char kind[8]{};
if (!r.token(kind,sizeof kind) || !unit_reference::same(kind,"W1")
|| !r.number(u.owner) || !u.owner || !r.number(u.birth) || !u.birth
|| !r.token(u.name,sizeof u.name) || r.at != n) return false;
if (!r.token(kind,sizeof kind)) return false;
u.exact = unit_reference::same(kind,"W2");
if (!u.exact && !unit_reference::same(kind,"W1")) return false;
if (!r.number(u.owner) || !u.owner || !r.number(u.birth) || !u.birth
|| !r.token(u.name,sizeof u.name)) return false;
if (u.exact && !(r.number(u.boot) && r.number(u.session))) return false;
if (r.at != n) return false;
static const char prefix[] = "Local\\openkal-unit-";
for (kal_uintptr i = 0; i < sizeof prefix - 1; ++i) if (u.name[i] != prefix[i]) return false;
kal_uintptr at = sizeof prefix - 1;
Expand All @@ -1348,9 +1383,10 @@ extern "C" {
int kal_process_job_create(kal_job* out, char* reference, kal_uintptr capacity, kal_uintptr* used) {
if (!out || !reference || !used) return kal_err_invalid;
if (capacity < 256) return kal_err_no_space;
if (!unit_compare()) return kal_err_not_supported;
if (!observable_units()) return kal_err_not_supported;
unit_identity u; u.owner = GetCurrentProcessId();
if (!unit_birth(u.birth)) return kal_err_not_supported;
if (!unit_birth(u.birth) || !unit_session(u.session)) return kal_err_not_supported;
u.boot = unit_boot();
unsigned char random[16]{};
const int random_rc = kal_random_fill(random,sizeof random); if (random_rc != kal_ok) return random_rc;
static const char prefix[] = "Local\\openkal-unit-", hex[] = "0123456789abcdef";
Expand All @@ -1361,7 +1397,8 @@ int kal_process_job_create(kal_job* out, char* reference, kal_uintptr capacity,
SetLastError(0); HANDLE job = CreateJobObjectW(nullptr,name);
if (!job) return okw::translate_win32(GetLastError());
if (GetLastError() == 183 /* ERROR_ALREADY_EXISTS */) { CloseHandle(job); return kal_err_again; }
unit_reference::writer w; w.text("W1;"); w.number(u.owner); w.next(); w.number(u.birth); w.next(); w.text(u.name);
unit_reference::writer w; w.text("W2;"); w.number(u.owner); w.next(); w.number(u.birth); w.next(); w.text(u.name);
w.next(); w.number(u.boot); w.next(); w.number(u.session);
if (!w.valid) { CloseHandle(job); return kal_err_no_space; }
if (!AssignProcessToJobObject(job,GetCurrentProcess())) { const auto error = GetLastError(); CloseHandle(job); return okw::translate_win32(error); }
const auto packed = okw::pack(job);
Expand All @@ -1372,7 +1409,22 @@ int kal_process_job_open(const char* reference, kal_uintptr length, kal_job* out
if (!out) return kal_err_invalid;
unit_identity u; if (!unit_parse(reference,length,u)) return kal_err_invalid;
if (!unit_compare()) return kal_err_not_supported;
HANDLE job = unit_open(u); if (!job) return okw::translate_win32(GetLastError());
HANDLE job = nullptr;
if (unit_earlier_boot(u)) {
// Nothing of that boot is left to open. The handle stands for the
// reference and is a job of no members; `observe' answers from the
// reference before it reads a handle.
job = CreateJobObjectW(nullptr,nullptr);
if (!job) return okw::translate_win32(GetLastError());
} else {
kal_u64 session = 0;
if (u.exact && (!unit_session(session) || session != u.session)) return kal_err_not_supported;
job = unit_open(u);
if (!job) {
const DWORD why = GetLastError();
return why == 2 /* ERROR_FILE_NOT_FOUND */ ? kal_err_not_supported : okw::translate_win32(why);
}
}
const auto packed = okw::pack(job);
if (!packed) { CloseHandle(job); return kal_err_no_memory; }
out->h = packed; return kal_ok;
Expand All @@ -1381,6 +1433,7 @@ int kal_process_job_observe(kal_job job, const char* reference, kal_uintptr leng
if (!state) return kal_err_invalid; *state = KAL_JOB_UNKNOWN;
unit_identity u; if (!unit_parse(reference,length,u)) return kal_err_invalid;
HANDLE original = okw::unpack(job.h); if (!original) return kal_err_invalid;
if (unit_earlier_boot(u)) { *state = KAL_JOB_EMPTY; return kal_ok; }
if (!unit_matches(original,u)) return kal_ok;
JOB_ACCOUNTING_ usage{};
if (!QueryInformationJobObject(original,JobObjectBasicAccountingInformation_,&usage,sizeof usage,nullptr)) return kal_ok;
Expand Down
84 changes: 84 additions & 0 deletions tests/a_unit_reference_names_its_boot_and_session.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
// What an observation of a unit answers (SPEC.md clause 7.18, version 0.26).
//
// A unit here is a named job in the session's namespace, and its reference
// (`W2') names the count of boots and the session beside the job's name. Until
// 0.23.0 it named neither: a reference of an earlier boot and one of another
// session both failed to open as a name that is not there, which a caller
// could not tell from a condition that passes. The cases alter a real
// reference one field at a time, which is how a reference from elsewhere reads
// to this program.
#include <string>
#include <vector>
#include <openkal/process.h>
#include <openkal/types.h>
import mcpplibs.mtest;

using namespace mcpplibs::mtest;

namespace {

std::vector<std::string> fields(const std::string& r) {
std::vector<std::string> out(1);
for (char c : r) { if (c == ';') out.emplace_back(); else out.back() += c; }
return out;
}
std::string joined(const std::vector<std::string>& f) {
std::string out;
for (std::size_t i = 0; i < f.size(); ++i) { if (i) out += ';'; out += f[i]; }
return out;
}

// What `open' answers, and the state an observation gives where it opens.
struct answer { int open = 0; kal_u32 state = KAL_JOB_UNKNOWN; };
answer ask(const std::string& reference) {
answer a; kal_job job{};
a.open = kal_process_job_open(reference.data(), reference.size(), &job);
if (a.open == kal_ok) {
kal_process_job_observe(job, reference.data(), reference.size(), &a.state);
kal_process_job_close(job);
}
return a;
}

} // namespace

UTest a_unit_reference_names_its_boot_and_session_test{"a_unit_reference_names_its_boot_and_session", [] {
expect(fatal((kal_process_props() & KAL_PROCESS_PROP_JOB_OBSERVE) != 0))
<< "this environment lets a reference be made, so observation is claimed";

// This program declares the unit and is its member for the whole test.
kal_job unit{}; char bytes[256]; kal_uintptr used = 0;
expect(fatal(kal_process_job_create(&unit, bytes, sizeof bytes, &used) == kal_ok)) << "a unit is declared";
const std::string reference(bytes, used);
const auto f = fields(reference);
expect(fatal(f.size() == 6 && f[0] == "W2")) << "the reference is `W2;owner;birth;name;boot;session': " << reference;

{
const auto a = ask(reference);
expect(a.open == kal_ok && a.state == KAL_JOB_OCCUPIED)
<< "a unit with a running member is occupied (open " << a.open << ", state " << a.state << ")";
}
// Another boot: every program of it has ended. A system that keeps no count
// of boots states none, and none is compared.
if (f[4] != "0") {
auto g = f; g[4] = std::to_string(std::stoull(f[4]) + 1);
const auto a = ask(joined(g));
expect(a.open == kal_ok && a.state == KAL_JOB_EMPTY)
<< "a reference of another boot is empty (open " << a.open << ", state " << a.state << ")";
}
{ // Another session: its names are not this session's.
auto g = f; g[5] = std::to_string(std::stoull(f[5]) + 1);
expect(ask(joined(g)).open == kal_err_not_supported) << "a reference of another session is not observable";
}
{ // A name the system no longer keeps: dropped with its last handle,
// whether or not a member remained.
auto g = f; char& last = g[3].back(); last = last == '0' ? '1' : '0';
expect(ask(joined(g)).open == kal_err_not_supported) << "a unit whose name the system dropped is not observable";
}
{ // The earlier form names its unit by name alone and is answered by it.
auto g = f; g[0] = "W1"; g.resize(4);
const auto a = ask(joined(g));
expect(a.open == kal_ok && a.state == KAL_JOB_OCCUPIED) << "a reference in the earlier form is answered by its name";
}
kal_process_job_close(unit);
}};
Loading