Skip to content

Latest commit

 

History

History
980 lines (727 loc) · 36.2 KB

reference.md

File metadata and controls

980 lines (727 loc) · 36.2 KB

jaal — reference

Every public type, what it's for, and what it refuses.

The other docs answer different questions: manual.md teaches jaal by building an app, design.md is how jaal is built, decisions.md is why it's built that way, concurrency.md is the safety model. This one is what you look things up in.

Each entry says what the thing does, the shape you write, and — the part worth reading — what it won't let you write. jaal's guarantees are mostly refusals, and a refusal you don't know about is just a confusing compiler error.


Contents


The program

A jaal program is one struct. There is no base class, no registration, no framework object to construct:

struct Counter {
    struct Model { int n = 0; };

    struct Inc {};
    struct Reset {};
    using Msg = std::variant<Inc, Reset>;

    using Cmd = jaal::Cmd<Msg>;          // + your effects: Cmd<Msg, beep>
    using Sub = jaal::Sub<Msg>;          // optional: timers, streams

    static Cmd init(Model& m);           // optional
    static Cmd update(Model& m, Inc);    // one per Msg case
    static Cmd update(Model& m, Reset);
    static Sub subscribe(const Model& m);// optional
    static std::optional<Msg> on(const Model& m, const Key& k);  // optional: input
};

Model

Your state. Any type. jaal never copies it behind your back — update takes it by reference and mutates in place.

Msg

A std::variant of everything that can happen. jaal dispatches each alternative to the update overload that takes it, so you never write a std::visit.

Msg may be a variant OF VARIANTS. That matters at scale: a flat variant costs sizeof(Msg) == sizeof(heaviest leaf) everywhere, so one fat message makes every message fat. Grouping by domain keeps it small.

Refuses: a Msg that isn't Sendable. It crosses to workers, so it must be safe to hand over. See Sendable.

update

static Cmd update(Model& m, SomeLeaf leaf);

Mutate the model, return a description of what should happen next. The signature is the whole contract: a reducer that returns its model can't also describe its effects as values, which is how apps end up reaching for a global seam instead.

One generic overload can catch a family:

template <class M> static Cmd update(Model&, M);

Refuses: a Msg case with no update. The error names the case and the line to add it — not a silently-ignored message.

subscribe

static Sub subscribe(const Model& m);

What the program wants running right now, as a function of state: timers, streams, host sources. The kernel diffs it against what's running and starts/stops to match. You never call "unsubscribe"; you stop returning it.

on: input

static std::optional<Msg> on(const Model& m, const Key& k);
static std::optional<Msg> on(const Model& m, const Click& c);
static std::optional<Msg> on(const Model&, jaal::sig s);    // signals are input too

How host input becomes a message. The same idea as update: one overload per event kind, picked by overload resolution.

  • It gets the model as it is when the event arrives. A burst like ^T m o (open a picker, then type into it) can't be judged against a stale model, because nothing was captured earlier.
  • Return a Msg, a case of it, or std::optional<Msg> (nullopt: not for this program right now).
  • An event kind with no overload is dropped. A host whose events match none of your overloads is a compile error, so on(const Key&) written against a host that sends KeyEvent can't silently do nothing.
  • If it throws, that's a fault at site input.
  • Unhandled interrupt / terminate / hangup still stop the program (exit 130 and friends), so forgetting on(sig) never makes it unkillable.

Optionally, say what input the program takes:

using Event = std::variant<Key, Click>;

Then every listed kind must have an on() (a missing one is a compile error, not a silently dropped click), and the test hosts pick it up: jaal::headless<App> and jaal::sim<App> take Key and Click without naming them again.

Input doesn't go through subscribe. There is nothing to keep in step and nothing for subs_key to cover. Routing one event costs ~14 ns.

Optional hooks

Hook Shape Without it
init Cmd init(Model&) model is value-initialised
subscribe Sub subscribe(const Model&) no timers or streams
on optional<Msg> on(const Model&, const E&) host input is dropped
subs_key K subs_key(const Model&), K equality-comparable subscribe() re-runs after every message
visual_hash uint64_t visual_hash(const Model&) host redraws every wakeup
needs_warmup bool needs_warmup(const Model&) no off-screen warm pass

A hook with the wrong signature doesn't compile. check_hooks<P>() runs at kernel::start, and a hook that's declared but can't be called fails with the shape it should have:

jaal: P::init is declared but its signature doesn't match.
Expected: static Cmd init(Model&).

So std::pair<Model, Cmd> init() left over from an older runtime can't silently throw the model away, which it once did.

subs_key in detail

subscribe() runs after every message unless you say otherwise. For a big model that walks lists and snapshots panes, that's real work on the input path.

static auto subs_key(const Model& m) {
    return std::tuple{m.panel_kind, m.streaming, m.composer.empty()};
}

A value, not a hash: a hash can collide, and a collision keeps a stale subscription alive — a timer that should have stopped. Equality can't be wrong that way.

The key must cover everything subscribe() reads. Debug builds check that for you: when subs_key says unchanged and subscribe() disagrees, that's a fault naming the problem. Input is on(), which reads the live model, so there is nothing else for the key to cover.


Effects: Cmd

A Cmd is a value describing side effects. Returning one doesn't do anything; the kernel interprets it after update returns.

using Cmd = jaal::Cmd<Msg, my_effect, another>;

The row — the effect list in the type — is what a host must be able to run. An effect not in the row won't convert, and a host that can't run one in the row fails to compile with the effect named.

Core effects

Factory Does
Cmd::none() nothing (also {})
Cmd::send(Msg) fold this message next, in the same step
Cmd::after(ms, Msg) fold it later
Cmd::after(key, ms, Msg) the same; a newer one with this key replaces it (debounce)
Cmd::quit(int = 0) end the program with this exit code
Cmd::now(f) f(now) → Msg; the clock as an effect, so tests control it
Cmd::random(f) f(rng) → Msg; seeded, so a test replays exactly
Cmd::perform<Ok>(body, args...) run body(args...) off the loop; its result arrives as Ok{result}
Cmd::attempt<Ok, Fail>(body, args...) same, and a throw arrives as Fail{...}
Cmd::task(body, args...) run on the pool; the body sends what it likes through a Sink
Cmd::task_isolated(body, args...) run on its own thread
Cmd::cancel(key) stop the keyed task with this key
Cmd::batch(a, b, ...) several, in order

Every way to run work takes an optional key first: Cmd::perform<Ok>("search", body, q). A keyed task replaces the running one with the same key. See keyed tasks.

Cmd::perform and Cmd::attempt

Most background work computes one thing and hands it back. perform is that, with no Sink and no send:

struct Loaded { std::string body; };
struct LoadFailed { std::string why; };

static Cmd update(Model& m, Open) {
    return Cmd::attempt<Loaded, LoadFailed>([](const std::string& url) {
        return fetch(url);                    // returns std::string, may throw
    }, m.url);
}
static Cmd update(Model& m, Loaded l)     { m.body = std::move(l.body); return {}; }
static Cmd update(Model& m, LoadFailed f) { m.error = std::move(f.why); return {}; }
  • perform<Ok>: the body's return value arrives as Ok{value}. A void body arrives as Ok{}. A throw is a task fault, like any task.
  • attempt<Ok, Fail>: a throw arrives as a message instead. Fail is built from whatever it can hold: Fail{e.what()} for a string field, Fail{ptr} for a std::exception_ptr, or Fail{}.
  • The body may take a std::stop_token first, when it wants to notice a cancel: [](std::stop_token st, std::string url) { ... }.
  • Parameters can be const T&, and the body can be a generic lambda.

Refuses, each with its own message: a body that captures, an argument that isn't Sendable, a body that can't be called with the arguments given, an Ok that can't hold the result, and a Fail that can't be built from an exception.

Keyed tasks: latest wins, and cancel

static Cmd update(Model& m, Typed t) {
    m.query = t.text;
    return Cmd::perform<Results>("search", &search, m.query);
}
static Cmd update(Model&, Esc) { return Cmd::cancel("search"); }

Starting a task with a key that's already running:

  1. asks the old one to stop (its stop_token fires)
  2. drops everything it sends from then on, including messages it had already queued before the replace

So update never sees a result for a query that isn't current, and there is no token to check by hand. Cmd::cancel(key) does steps 1 and 2 without starting anything; cancelling a key with nothing running is a no-op.

The dropping is decided on the loop thread, so no thread timing can let a stale result through. tests/kernel/keyed_task_test.cpp runs the search-as-you-type shape across 300 sim seeds to check it.

Keys are per program: a child or children entry gets its own key space, so two tabs both running "search" are two tasks.

A key can carry a placement: jaal::key("scan", jaal::fx::isolated).

Keyed timers debounce. after takes a key too. Each new one with the same key replaces the pending timer, so the message arrives once, after the input settles:

static Cmd update(Model& m, Typed t) {
    m.text += t.c;
    return Cmd::after("settle", 200ms, Search{});    // restarts on every key
}

If the old timer had already fired but its message wasn't folded yet, that message is dropped too. Tasks and timers share key space, so Cmd::cancel("settle") stops whichever is pending.

Cmd::task

For work that sends more than one message (progress, partial results), or none:

return Cmd::task(
    [](jaal::Sink<Msg> out, std::stop_token st, std::string url) {
        auto body = fetch(url, st);
        out.send(Loaded{std::move(body)});
    },
    m.url);                       // arguments, BY VALUE

One rule for every body (task, stream, perform, attempt):

  • it captures nothing; everything it needs is an argument after it
  • it may be a lambda, a generic lambda, or a plain function (&load)
  • parameters can be T or const T&
  • std::stop_token comes after the Sink, only if the body wants it
  • const jaal::unlocked& comes first, only if it takes locks
Cmd::task([](jaal::Sink<Msg> out, const std::string& url) { ... }, m.url);
Cmd::task(&poll_device, m.port);

Refuses:

  • a body that captures anything. Everything it needs is an argument. A capture can outlive the call that made it; an argument is copied.
  • an argument that isn't Sendable. It crosses threads.
  • a body that can't be called with the arguments given.

Each fails with a named diagnostic, not a template dump.

task_isolated is identical but gets its own thread, for work that blocks for a long time and shouldn't occupy a pool slot.

The stop_token

A task's std::stop_token fires when:

  • a keyed task is replaced or cancelled
  • the program shuts down

An unkeyed task is fire-and-forget: only shutdown stops it. Give it a key if anything should be able to stop it.

You want Use
run once, result comes back Cmd::perform / Cmd::attempt
run once, the newest replaces the rest the same, with a key
stop it from a later step a key, then Cmd::cancel(key)
run while the model says so, stop when it doesn't Sub::stream
several messages over time Cmd::task (keyed, if it should be stoppable)

Cmd::batch and ordering

Effects run in the order given, and interpretation stops at the first quit. So this drops the save:

return Cmd::batch(Cmd::quit(), save_settings(m));   // ✗ never runs
return Cmd::batch(save_settings(m), Cmd::quit());   // ✓

Cmd::map

Retarget a child's Cmd at the parent's Msg:

child_cmd.map([](Child::Msg m) { return Parent::ToChild{id, m}; })

Refuses: a capturing mapper when the Cmd holds a task — the mapper crosses threads with it.

Your own effects

An effect is a payload plus a name:

struct SaveFile { std::string path, contents; };
using save_file = jaal::pure_fx<SaveFile, "save_file">;

using Cmd = jaal::Cmd<Msg, save_file>;

The host runs it:

void handle(SaveFile e) { write(e.path, e.contents); }

An effect may answer — return a Msg or std::optional<Msg> from handle and it's folded in the same step. That's for work that must happen on the loop thread and produce a result: handing the terminal to $EDITOR and reporting how it exited.


Subscriptions: Sub

What the program wants running, as a function of state.

static Sub subscribe(const Model& m) {
    if (!m.running) return Sub::none();
    return Sub::every(std::chrono::milliseconds{16}, Tick{});
}

Everything in a Sub has a lifetime (started, kept, stopped) and a key. The reconciler keeps a running source as long as a source with the same key keeps being returned, so a timer keeps its phase across unrelated model changes. (Input isn't a subscription: see on.)

Sub::every

Sub::every(std::chrono::milliseconds{16}, Tick{})

Keyed by interval + ordinal, so two timers at the same interval are two timers.

Sub::stream

Long-running work that should run exactly while the model says so: a download while downloading, a log tail while a pane is open.

static Sub subscribe(const Model& m) {
    if (!m.downloading) return Sub::none();
    return Sub::stream("dl:" + m.url,                       // key
        [](Sink<Msg> out, std::stop_token st, std::string url) {
            for (auto chunk : fetch(url, st)) {
                if (st.stop_requested()) return;
                out.send(Progress{chunk.size()});
            }
            out.send(Done{});
        },
        m.url);
}
  • Same key next subscribe() → kept running, not restarted.
  • Key gone → stop_token fires. Stopping is not asking for it.
  • Messages from a stopped generation are dropped, so a late result can't land in a model that moved on.

Same body rules as task: captureless, Sendable arguments.


Talking back: Sink

How a worker sends messages home.

out.send(Msg{Loaded{...}});     // returns bool

A Sink is a weak handle to the loop's mailbox:

  • The loop is gone → send returns false. It never writes into freed memory, so a worker outliving the loop is safe rather than fatal.
  • It's Sendable, so it can be a task argument.
  • Only the kernel mints one. The constructor is private.

A default-constructed Sink is closed — send returns false. That's deliberate: a closed sink is harmless.


Composition

child

One child program in a fixed slot.

struct ToEditor { Editor::Msg msg; };
using Ed = jaal::child<Editor, App, ToEditor>;

struct Model { Editor::Model editor; };
static Cmd update(Model& m, ToEditor t) { return Ed::update(m.editor, t); }
static Sub subscribe(const Model& m)    { return Ed::subscribe(m.editor); }
static std::optional<Msg> on(const Model& m, const Key& k) { return Ed::on(m.editor, k); }

The child's Cmds, Subs and input are retargeted at the parent's Msg. Its stream and task keys live under the Wrap's name, so two children of the same type never collide. (Ed::subscribe(m, "prefix") names it yourself.)

Ed::on(m.editor, ev) is the child's own on, on its own model, wrapped. The parent decides who gets input: forward to the focused child, try one then the other, or handle the key itself first.

Refuses: a Wrap that isn't a case of the parent's Msg, or a child whose Cmd row has an effect the parent's doesn't list.

children

A keyed list of child programs — tabs, panes, sessions.

struct ToTab { int id; Tab::Msg msg; };
using Tabs = jaal::children<Tab, App, ToTab>;

struct Model { Tabs::map tabs; };

static Cmd update(Model& m, ToTab t)     { return Tabs::update(m.tabs, t); }
static Cmd update(Model& m, NewTab)      { return Tabs::add(m.tabs).second; }
static Cmd update(Model& m, CloseTab c)  { Tabs::remove(m.tabs, c.id); return {}; }
static Sub subscribe(const Model& m)     { return Tabs::subscribe(m.tabs); }
static std::optional<Msg> on(const Model& m, const Key& k) {
    return Tabs::on(m.tabs, m.focused, k);  // input to the focused tab
}

Removing a child stops its subscriptions — that's what keying is for. Each child's stream and task keys live under its id, so two tabs both running "search" are two searches.

Use it when children RUN. A list of rows in a picker is not a list of programs: if the entries have no Model of their own, no timers and no streams, children<> buys you an id-wrapped Msg layer and nothing else.

debounce<T>

For most debouncing, a keyed after is enough and needs nothing in the model: Cmd::after("settle", 200ms, Search{}). Use debounce<T> when the value matters too, so that a result can be checked against the question it answered:

A value whose in-flight work is invalidated by token, so a late answer to a superseded question is dropped without a hand-rolled staleness stamp.

It is a value you put in the model, not a Cmd factory:

struct Model { jaal::debounce<std::string> query; };

static Cmd update(Model& m, Typed t) {
    const auto tok = m.query.set(t.text);          // invalidates older tokens
    return Cmd::after(200ms, Msg{RunSearch{tok}});
}

static Cmd update(Model& m, RunSearch r) {
    if (!m.query.ready(r.token)) return {};        // superseded while waiting
    return Cmd::task(search_body, m.query.value(), r.token);
}

static Cmd update(Model& m, Results res) {
    if (!m.query.ready(res.token)) return {};      // a late answer
    m.rows = std::move(res.rows);
    return {};
}
Call Means
set(v) new value; returns the only token now ready
invalidate() bump the token without changing the value — "everything in flight is stale" (Esc, panel closed)
ready(t) is t from the most recent set?
value() / token() / empty() the current value, token, and "nothing typed yet"

Frozen- and Sendable-clean (a value and a counter), so it sits in any model and rides along into a task.

There is also throttle in the same header for the other shape: let something through at most once per interval, and remember whether anything was dropped so the trailing edge still runs. That's for a progress bar fed by a fast stream — redraw 30 times a second, but don't lose the final 100%.


Safety types

The full reasoning is in concurrency.md; this is what each one is and what it refuses.

Sendable

"Safe to hand to another thread." Checked structurally, field by field.

Refuses raw pointers, references, views (string_view, span) and shared_ptr-to-mutable — anything that may point at memory another thread frees or mutates.

Opt in when you know better, with the reason written down:

// This shared_ptr is one atomic<bool>, written by the UI thread and read by
// the worker — the narrowest possible conversation.
template <>
inline constexpr bool jaal::sendable_opt_in<std::shared_ptr<std::atomic_bool>> = true;

When something isn't Sendable and you can't see why:

jaal::sendable_reason<MyType>();   // names the offending field

Frozen

Deeply immutable. shared<T> requires it, so many readers need no lock.

shared<T>

Immutable value, many readers, no lock. No null, no raw pointer in, no write after construction.

Sync

Many threads may use the same T& at once. Checked field by field on a plain struct: a field is fine when it's const and Frozen, a guarded, a published, an atomic number, or a const owning pointer to something Sync. Anything writable fails. A class jaal can't walk opts in with sync_opt_in.

co_owned<T>

State a background job shares with its owner. Like shared<T> (never null, move copies, built only by make()), but make() requires Sync<T> and it hands out T&. co_owned<T>::of(self) gets the handle from inside an object that derives from enable_shared_from_this.

Refuses: a T with a writable field, naming the field.

guarded<T, R>

State behind a lock you cannot forget to take, taken in an order the compiler checks:

using cache_rank = jaal::rank<40, "app.cache">;
guarded<std::map<std::string, int>, cache_rank> cache;     // R defaults to jaal::leaf

cache.with(cap, [](auto& m, std::string k) { ++m[k]; }, key);       // exclusive
int n = cache.read(cap, [](const auto& m) { return int(m.size()); });  // shared

cap is a capability (core/capability.hpp): const jaal::unlocked& (nothing held), const jaal::held<Q>& (inside a lock ranked Q), or a const jaal::below<S>& parameter. Taking a lock ranked R needs one that proves every held lock ranks lower. A body may take const jaal::held<R>& first to take further locks, which must rank above R:

outer.with(cap, [](const jaal::held<outer_rank>& h, Outer& o) {
    inner.with(h, [](Inner& i) { ... });   // compiles only if inner ranks above outer
});

Threads get their root capability at entry: a job, task, stream body or scope helper may take const jaal::unlocked& first, and main uses jaal::thread_root([&](const jaal::unlocked& cap) { ... }). Blocking calls (wait_with, wait_with_for, scope, pool::shutdown, worker_group::stop) take exactly const jaal::unlocked&.

The arguments go after the lambda, not into a capture: inside with/read you can only reach what you were given, and a capability is never Sendable, so the body's own held<R> is the only one it has.

Refuses: a lock taken out of rank order, two leaves together, re-entry, a wait under a lock, a missing or forged capability (each a compile error, tests/compile_fail/capability.cpp); returning something that points into the guarded value; a T that owns a pool or worker_group (its destructor would wait under the lock).

loop_bound<T>

State only the loop thread may touch. Reaching the value needs a loop_token, which can be neither copied nor moved (so it can't be smuggled into a task body) and which cannot be forged: loop_key's constructor is private.

The kernel arms a per-thread identity for its whole lifetime, so on the loop you just call with():

jaal::kernel::loop_bound<Cache> g_cache;        // a render cache, say

// In update() or view() — on the loop, so this works:
g_cache.with([](Cache& c) { c.put(key, value); });
auto hit = g_cache.with([&](Cache& c) { return c.get(key); });   // a COPY out

On a worker there is no token to be had, and the call aborts naming the rule rather than quietly returning that thread's own empty copy — the silent wrong answer is the bug this type exists to kill. Use on_loop() directly if you want the token, or on_loop() with no argument to just ask.

with() won't let a reference or pointer into the state escape (these are usually evicting caches, so the handle would dangle); return an owning value — a copy, or a shared_ptr<const T>.

Use it instead of thread_local.

scope / nursery

Structured concurrency: helpers that can't outlive their scope. n.spawn(body, args...) and n.spawn_n(count, body, args...) take a captureless body and Sendable args, like a task; shared state goes in a co_owned<T>. scope() joins every helper, and a handle joins its helper when destroyed. A handle is pinned: no moving it out to extend its life.

Refuses: a capturing helper, a pointer or view argument, handing a helper the nursery or a handle (D45).

jaal::parallel_for(cap, n, width, body) runs body(i) for i in [0, n) across width threads (the caller is one) and returns when all are done; body is borrowed only for the call, which joins before it returns.

handle

An owned OS handle. No copy, no implicit conversion from int, no double-close. borrowed_handle for a non-owning view, and the two don't convert into each other.

stop_group

Cancel and wait for work running on threads jaal doesn't own. join() hands a member a real std::stop_token; stop_and_wait(grace) stops them all and waits for them to leave. Refuses: a join() after stopping has begun.

worker_group

An object's background jobs, where stop() is a hard barrier with no grace. When it returns, no job is running, so the owner may free what the jobs wrote into. Use it when a job touches something a third party frees right after stop; pool's bounded shutdown abandons, which is wrong there. Refuses: a post() after stop() (dropped). A job that never returns hangs stop(), so give jobs their own timeouts.

Jobs here and on pool follow the task rule: post(body, args...) with a captureless body(stop_token, args...) and Sendable args. Shared state goes in as a co_owned<T>.

Refuses: a capturing body, a pointer or view argument.

native_process

A child process, chosen per OS (select.hpp): posix_process or windows_process. Both satisfy Process and pass the same conformance suite. The exit handle and the output pipes go into the reactor like any other readiness. On Windows the child runs in a kill-on-close job object, so stop(_, tree) reaches every descendant; graceful acts as forceful there, since an arbitrary program has no SIGTERM. Read Windows pipes with read_some/write_some, which never wait. process_spec::windows_command_line passes a command line verbatim, and a cmd /c <payload> argv passes its payload as written, since cmd.exe doesn't parse by CommandLineToArgvW rules.


Hosts

A host is what turns the outside world into events and carries out effects. jaal ships no host — hosts.md is the guide to writing one.

Minimum: a handle() for every effect in the program's row. Optionally attach/on_ready to watch file descriptors, present to draw, wait_hint to sleep well.

jaal::run<App>(host);

⚠️ Template the context hooks. If someone derives from your host to add effects, the context becomes host_context<Derived>. A hook fixed to host_context<Base> doesn't match, and jaal rejects it at compile time with the shape it expected. Take the context as a template parameter.

headless

Run a program with no host at all. Effects are recorded; you drive with messages, input events and a clock you move.

jaal::headless<App> h;
h.send(Msg{Inc{}});
h.event(Key{'q'});             // through on(); App::Event says what it takes
h.advance(200ms);              // timers fire at their own times
h.run_until_idle();            // wait for background tasks to land
CHECK(h.model().n == 1);

given

Runs a reducer and its tasks inline, with no threads: when(msg) folds a message, settle() runs the tasks and perform bodies it asked for and folds what they send, expect(...) checks the model, expect_effect<D>(n) checks what the last update asked for.

sim

The property-testing host — see below.


Testing

Reducers need no host

update is a pure function. Call it:

Model m;
Cmd c = App::update(m, Inc{});
CHECK(m.n == 1);

And assert on the effects, because they're values:

CHECK(count<save_settings>(c) == 1);

That's the payoff of effects-as-data. A reducer that performs its effects can only be tested by installing a fake and inspecting it afterwards.

sim — the interleavings you didn't think of

jaal::sim<App> s{seed};

s.check("cursor is in range", [](const App::Model& m) {
    return m.cursor >= 0 && m.cursor <= (int)m.text.size();
});

s.at(0ms,  Msg{Type{'h'}});
s.at(10ms, Msg{Submit{}});
s.at(25ms, Msg{Cancel{}});

auto r = s.run();
CHECK(r.ok());

Simulated time, seeded task-completion order, every invariant re-checked after every message. sim_options can inject crashed and lost tasks.

Input goes in the same way, through your on():

jaal::sim<App> s{seed};         // App::Event says what input it takes
s.input(5ms, Key{'q'});         // at sim time 5ms, on(model, Key{'q'})

explore runs the same scenario across many seeds — each reorders task results — and stops at the first break:

auto out = jaal::explore<App>(1, 200, opt, [](auto& s) { ... });
CHECK(out.ok());

Make sure it isn't vacuous. A sim that never steps passes everything. Add a deliberately false invariant once and watch it break; if it doesn't, your scenario isn't driving the machine.

Invariants worth asserting

Structural ones — things true after any message, which is what makes them safe against a random order:

  • a derived flag agrees with the state it's derived from
  • an index is in range
  • two representations of one fact don't disagree

Compile-fail tests

jaal's own guarantees are tested by code that must not build (tests/compile_fail/, driven by jaal_compile_fail). Each case pins the expected diagnostic, so it can't "pass" by failing for the wrong reason — a typo, a missing include.

A guarantee without a compile-fail test is a claim. If you add a refusal, add the case. And pair it with a positive test: a negative case can pass because of a typo, and only the control catches that.

The ban-list

tests/lint/banlist.cmake keeps raw std::thread, std::mutex, std::atomic, thread_local, const_cast, sink_access and loop_key out of code that should use the safe types. An allowlist names the files that may use each, because there they are the implementation.

It scans a root you give it, so point it at your own tree too:

add_test(NAME concurrency_banlist
         COMMAND ${CMAKE_COMMAND}
                 -DROOT=${CMAKE_SOURCE_DIR}/src
                 -DALLOW=${CMAKE_SOURCE_DIR}/tests/lint/allowlist.txt
                 -P .../jaal/tests/lint/banlist.cmake)

jaal running it over jaal says nothing about your code.


Diagnostics

jaal's errors are written to be read. Most name the rule:

Message Means
a task body must not capture anything pass it as an argument
a task argument is not Sendable sendable_reason<T>() names the field
a Sink's Msg must be Sendable your Msg holds a pointer or view
effect ... not in this Cmd's row add it to Cmd<Msg, ...>
host '...' cannot run effect '...' add handle() for it
P::on is declared, but no overload takes an event this host sends the parameter type doesn't match the host's event type
guarded::with/read returns something that points into return a copy
could not convert ... to 'jaal::below<...>' a lock taken out of rank order, or under one ranked at/above it: reorder, or give the outer lock a lower rank
... to 'const jaal::unlocked&' from a held<...> a blocking wait/join/shutdown inside a lock body: move it out
subs_key() reported no change, but subscribe() now returns different sources a field is missing from the key
a perform body must not capture anything pass it as an argument after the body
perform<Ok>: can't build the message Ok{result} give Ok one field of the body's result type
attempt<Ok, Fail>: Fail must be a case of Msg built from ... give Fail a std::string field
P::init is declared but its signature doesn't match the message gives the shape to use

Cheat sheet

// ── program ──────────────────────────────────────────────────────────
struct App {
    struct Model { /* state */ };
    using Msg = std::variant</* leaves */>;
    using Cmd = jaal::Cmd<Msg /*, effects */>;
    using Sub = jaal::Sub<Msg /*, sources */>;

    static Cmd init(Model&);                    // optional
    static Cmd update(Model&, Leaf);            // one per leaf
    static Sub subscribe(const Model&);         // optional: timers, streams
    static std::optional<Msg> on(const Model&, const Key&);  // optional: input
    static std::optional<Msg> on(const Model&, jaal::sig);   // signals too
    using Event = std::variant<Key>;            // optional: checked, used by tests
    static auto subs_key(const Model&);         // optional, big win
};

// ── effects ──────────────────────────────────────────────────────────
Cmd::none()  Cmd::send(msg)  Cmd::after(ms, msg)  Cmd::quit(code)
Cmd::now(f)  Cmd::random(f)  Cmd::batch(a, b)     cmd.map(f)
Cmd::perform<Ok>([key,] body, args...)        // result -> Ok{result}
Cmd::attempt<Ok, Fail>([key,] body, args...)  // ... and a throw -> Fail{what}
Cmd::task([key,] body, args...)               // body sends through a Sink
Cmd::after([key,] ms, msg)                    // keyed: debounce
Cmd::cancel(key)                              // stop a keyed task or timer
// a key: the latest task with it wins, older ones stop and their messages drop

// ── subscriptions ──────────────────────────────────────────────────────────────────
Sub::none()  Sub::every(ms, msg)  Sub::batch(a, b)
Sub::stream(key, body, args...)            // runs while returned; STOPS when not

// ── composition ───────────────────────────────────────────────────────────────────────
using Ed   = jaal::child<Editor, App, ToEditor>;         // one slot
using Tabs = jaal::children<Tab, App, ToTab>;            // keyed list
Ed::update(m.editor, w)   Ed::subscribe(m.editor)   Ed::on(m.editor, ev)
Tabs::add(m.tabs, id)     Tabs::remove(m.tabs, id)  Tabs::on(m.tabs, id, ev)

// ── safety ───────────────────────────────────────────────────────────
Sendable<T>  Frozen<T>  shared<T>  guarded<T, R>  loop_bound<T>  scope  handle
rank<N, "name">  leaf  unlocked  held<R>  below<R>  thread_root  JoinFree<T>

// ── testing ──────────────────────────────────────────────────────────
jaal::headless<App>            // no host, records effects
jaal::given<App>               // tasks run inline
jaal::sim<App, Event>          // simulated time, seeded order, invariants
                               //   s.at(t, msg)  s.input(t, event)
jaal::explore<App, Event>(...) // the same, across seeds

The one thing that costs real debugging time

An unkeyed task can't be stopped. Its stop_token only fires at shutdown. If anything should stop it, give it a key.