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
9 changes: 9 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,15 @@ if(WIN32)
add_compile_definitions(NOMINMAX WIN32_LEAN_AND_MEAN)
endif()

# Links run at most this many at once under Ninja. A debug-info link of a ladder test binary takes several GB, and a
# build parallel to the core count links as many binaries at once, which is what exhausts a 16 GB CI runner; compiles
# keep the full parallelism.
set(MORPH_LINK_JOBS 2 CACHE STRING "Links Ninja runs at once (0: no limit)")
if(CMAKE_GENERATOR MATCHES "Ninja" AND MORPH_LINK_JOBS GREATER 0)
set_property(GLOBAL APPEND PROPERTY JOB_POOLS morph_link=${MORPH_LINK_JOBS})
set(CMAKE_JOB_POOL_LINK morph_link)
endif()

option(MORPH_BUILD_TESTS "Build tests" ON)
option(MORPH_BUILD_EXAMPLES "Build examples" ON)
option(MORPH_BUILD_BANK_EXAMPLE "Build the SQLite/Lightweight bank example (heavy deps)" OFF)
Expand Down
51 changes: 50 additions & 1 deletion docs/KEEPING-SCREENS-CURRENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,54 @@ Rules of thumb:
- **`updates<R>` and `changes<R>` together mean the whole type**: the change is reported without keys.
- Declare each action's effects in **one** place. A header included by several translation units is still one
declaration; a second, different declaration for the same action is refused.
- **A write that lands in another module's record** is declared by the code that composes the two modules, with
`BRIDGE_ADD_EFFECTS` (below). The action's own module cannot name that record, and a second
`BRIDGE_REGISTER_EFFECTS` is refused.

### Effects the composing code adds

An action sometimes changes a record of a module it must not include: a billing action that posts a ledger entry in
its own transaction, or an organisation action that changes which samples a lab screen lists. The module cannot write
that effect, and the application that links both can.

```cpp
// app/src/ledger_wiring.cpp, which includes both modules
BRIDGE_ADD_EFFECTS(lims::PostInvoice, ::morph::effects::changes<lims::JournalEntryView>)
```

- The addition is **unioned** with the action's own `BRIDGE_REGISTER_EFFECTS`; it can never remove an effect, and
`none` is not accepted in it. An action with no declaration of its own has the additions alone.
- Two different `BRIDGE_REGISTER_EFFECTS` for one action are still refused. An addition is the only second source.
- It takes any of `updates<R>`, `changes<R>` and `changesInstance`, and `R` must be a registered record. An addition
for an action nobody registered, or for an unregistered record, is refused when the registries are first read, with
the other problems, and never ignored.
- It expands to nothing under `MORPH_CLIENT_ONLY`.
- Put it in a translation unit that is always linked into the server, such as the one that wires the modules together.
A static library's object that nothing references is dropped, and its addition with it.

### Facts that change with time alone

A list filtered by a deadline changes when the clock passes the deadline, though no action runs. The model says when,
and the server tells the watchers at that instant.

```cpp
// A registered read beside the others: the next instant, after now, at which a requisition's scope moves.
struct NextRequisitionDeadline {};
std::optional<morph::time::DateTime> ProcurementModel::execute(NextRequisitionDeadline const&);
BRIDGE_REGISTER_ACTION(lims::ProcurementModel, lims::NextRequisitionDeadline, "NextRequisitionDeadline")
BRIDGE_REGISTER_CHANGES_AT(lims::ProcurementModel, lims::NextRequisitionDeadline, lims::RequisitionView)
```

- The action reports a fact and nothing else. It arms no timer and posts no work; the server owns the clock.
- It must return `std::optional<morph::time::DateTime>`: an instant strictly after the model's own now, or `nullopt`
when nothing is pending. It declares no effects, takes no fields, and reads from the same clock the server uses
(`ServerConfig::clock`).
- At that instant the server marks every listed record, and every record derived from it, as changed, as if an
action declaring `changes<R>` had run, and then asks for the following instant. It asks again after any action
whose effects name one of the records, since the next instant may have moved.
- A reporter that is not a registered action, that declares effects, or that names an unregistered record is
refused with the other registry problems.
- In a local-mode client there is no server, so nothing is told at the instant: use `refreshEvery` there.

## Records

Expand Down Expand Up @@ -216,7 +264,8 @@ Work through it every time you add an action or change what one does. A coding a
every action's effects.
5. **Would a key alone leak something to another user?** Add `privateKeys` to the record.
6. **Write `BRIDGE_REGISTER_EFFECTS` (`<morph/core/effects.hpp>`) directly under the action's
`BRIDGE_REGISTER_ACTION`.**
`BRIDGE_REGISTER_ACTION`.** A record the action's module cannot include is added by the composing code with
`BRIDGE_ADD_EFFECTS`.
7. **Remove any refresh the screens did by hand**: an `onSuccess` refetch that the effects now cover.
8. **Build and run the screen tests.** A bad declaration fails when the server starts. Check that the bundle loads
with no warnings ([Testing](#testing)).
Expand Down
30 changes: 30 additions & 0 deletions docs/spec/core/backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -783,6 +783,8 @@ changes it.
| `payloadCompleteness` | `Lenient` | See [`PayloadCompleteness`](#payloadcompleteness--enforcing-the-action-evolution-policy). |
| `services` | empty | `IEnvelopeService` extensions; see [Envelope services](#envelope-services). A null entry makes the constructor throw `std::invalid_argument`. |
| `coalesceWindow` | `50 ms` | How long a connection's changes are merged before one `changes` event is sent; see [Coalescing](#coalescing). |
| `clock` | the system clock | The server's "now", read by [time-derived fan-out](#time-derived-fan-out). A test supplies one it advances by hand. |
| `clockRecheck` | `1 s` | The longest the server sleeps before reading `clock` again; see [time-derived fan-out](#time-derived-fan-out). Not positive is refused by the constructor. |

```cpp
using LogProvider = std::function<std::shared_ptr<morph::journal::IActionLog>(
Expand Down Expand Up @@ -1324,6 +1326,32 @@ through `dispatchExecute`.
second plus one per 256 keys (or topics) the connection is sent.
A burst of one hundred writes to one type reaches each watching
connection as one event, so one refetch per showing query.
- <a id="time-derived-fan-out"></a>**Time-derived fan-out.** Some records change
with no action behind them: an approval's scope moves from a site to its company at a
deadline. A model reports such a fact through an action registered with
`BRIDGE_REGISTER_CHANGES_AT` (see [registry.md, "Effects"](registry.md#effects)), and the
server, which owns the clock, does the rest through the same `fanOut` an action's effects
take:
- *Asking.* The first envelope the server handles, and every later fan-out that names one of a
reporter's records, schedules one ask for that reporter: a fresh instance of its model is made
through the `ModelRegistryFactory`, the action is dispatched on it with an empty payload on
a model strand (never the server strand, whose tasks must not block), and the instance is
dropped. An ask in flight is not repeated; a change that arrives during it asks once more
when it ends, because the answer may predate the change. An ask that throws is logged and
leaves the reporter with no instant until a later change asks again.
- *Waiting.* The server keeps the instant it was told and sleeps on its strand timer for
`min(instant - clock(), clockRecheck)`. It never trusts the elapsed sleep: after each wake it
reads `clock` again, because a system clock can be set and an injected one is advanced by a
test without any sleep. The instant has come when `clock() >= instant`.
- *Firing.* The server fans out a whole-type `changes` for each listed record, and every
record derived from it, as `fanOut(changes, 0, "")`: no caller, so no connection is exempt
and a `privateKeys` record reaches every watcher without its keys. Re-authorisation and
coalescing apply as to any fan-out. It then asks again for the following instant.
- *What the model must do.* Report an instant strictly after its own now, from the same
clock the server is configured with, so a reported instant that has come is never reported
again. The model is not told when it fires, and nothing in it is scheduled.
- A record changed by time alone and by an action declares the action's effects as usual;
the two paths meet in `fanOut`.
- **The registries are read at construction.** Every `RemoteServer`
constructor reads the record and effects registries once, so a process whose
declarations are invalid fails with `EffectsRegistrationError` when the server
Expand Down Expand Up @@ -2471,6 +2499,8 @@ server: each call is a loop task, so the loop serialises them.
| `payloadCompleteness` | `PayloadCompleteness`; default `Lenient`. |
| `services` | `std::vector<std::shared_ptr<IEnvelopeService>>`: extensions consulted, in order, for a kind the server does not answer itself; a null entry throws `std::invalid_argument`. See [Envelope services](#envelope-services). |
| `coalesceWindow` | `std::chrono::milliseconds`, default `50 ms`: how long a connection's changes are merged before one `changes` event is sent; zero sends each fan-out at once; negative throws `std::invalid_argument`. See [Coalescing](#coalescing). |
| `clock` | `std::function<morph::time::DateTime()>`, default empty (the system clock): the server's "now" for [time-derived fan-out](#time-derived-fan-out). |
| `clockRecheck` | `std::chrono::milliseconds`, default `1 s`: the longest sleep before `clock` is read again; not positive throws `std::invalid_argument`. |

### `SimulatedRemoteBackend`

Expand Down
37 changes: 36 additions & 1 deletion docs/spec/core/registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -1773,6 +1773,30 @@ for every action, which records its result holds.
two such halves). It belongs beside the action's registration, in a header
or a source file: each translation unit that sees it registers the same
declaration, which is one.
- **Additions from the composing code.** `BRIDGE_ADD_EFFECTS(A, effects...)`
stores `{Kind, std::type_index?}` per effect under the action's id in
`detail::mutableAddedEffectsRegistry()`, apart from the base declarations.
It is for code that links two modules and so can name a record the action's
own module cannot: a write that crosses a module boundary is declared by the
composer, not by either side. The effects are `updates<R>`, `changes<R>` and
`changesInstance`; `none` is refused at compile time, since an addition adds
and `none` adds nothing. Repeating an addition, in any order and from any
number of translation units, is a no-op, and additions from several
composers are unioned. Like `BRIDGE_REGISTER_EFFECTS`, it asserts the
registration latch, defines no specialisation and compiles out under
`MORPH_CLIENT_ONLY`.
- **Time-derived facts.** `BRIDGE_REGISTER_CHANGES_AT(Model, A, records...)` registers action `A`
of `Model` as the reporter of an instant: the next moment at which the listed records change by
the passage of time alone, with no action behind it (an approval that escalates at a deadline).
`A`'s result must be `std::optional<morph::time::DateTime>`, checked at compile time; the
instant is strictly after the model's own now, and `nullopt` means nothing is pending. The
registrar stores `{actionId, modelId, record types}` in
`detail::mutableChangeTimesRegistry()` beside the effects, lazily matched like them, and
compiles out under `MORPH_CLIENT_ONLY`. The model only reports a fact: it arms no timer and
posts no work, and does not know the server exists. Naming no record is a compile error.
Resolution refuses, with the other problems, a reporter that is no registered action, one
that also declares effects (it reads, and the server runs it unprompted), and one naming a
record that is not registered. `Resolved::changeTimes` lists the reporters and `effects::changeTimesOf()` reads them.
- **Idempotent per action.** Each action id keeps its distinct declarations;
one equal to a stored one, in any order, is not added again. Two distinct
declarations are a conflict, recorded rather than thrown so the registrar
Expand All @@ -1786,6 +1810,14 @@ for every action, which records its result holds.
latch in a debug build. Resolution cannot run at the latch:
`closeRegistrationPhase()` is `noexcept`, and a release build closes it only
when the application asks.
- **The union.** An action's effects are its base declaration unioned with
its additions. An addition never removes an effect: a base `none` is dropped
when an addition exists, because the action then changes something, but no
base `updates`, `changes` or `changesInstance` is ever lost. An action with
additions and no base declaration has the additions alone. Two *different
base* declarations are still a conflict; additions never make or hide one.
Every addition passes the same checks as a base effect (see Validation), so
an `updates<R>` addition needs a keyed `R` that the action's result holds.
- **Matching.** For each action, its result slots are taken in path order, and a
slot is kept when its type is a registered record and no kept slot's path
contains it (a path contains itself and every path below it; `""` contains
Expand All @@ -1799,6 +1831,9 @@ for every action, which records its result holds.
- an action with two different effects declarations. A declaration is a
set, so a repeated effect counts once and order does not matter;
- `none` together with any other effect in one declaration;
- an addition for an action id that no action registered: it would declare
effects for nothing, so a misspelt or removed action is refused rather than
ignored. The record of an addition is checked as a base effect's is;
- `updates<R>` or `changes<R>` where `R` is not a registered record;
- `updates<R>` where `R` has no key, or where the action's `recordsOf` does
not name `R`;
Expand Down Expand Up @@ -1830,6 +1865,6 @@ for every action, which records its result holds.
`changesInstance` and `none`. `recordNamed(name)` points into the resolved
copy of the record registry, valid for the life of the process.
- **Testing.** `detail::resolveForTesting(records, slots, effects,
slotConflicts)` runs the same resolution over registries a test builds, so an
slotConflicts, additions)` runs the same resolution over registries a test builds, so an
invalid configuration can be exercised without making the process registry
invalid for the rest of the suite.
25 changes: 19 additions & 6 deletions docs/spec/forms/engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,24 @@ it. A view mounted on it is destroyed first.
engagement, and its members' and rows') as `prefill`, `reset` or `assign` last left it, and as it was built.
`refill(bodyJson)` loads like `prefill`, except that a top-level field whose snapshot differs (the user changed
it since) keeps what was entered. It is for a later value of the record already being edited; `prefill` is for
another record. A successful submission of an explicit form ends the edit of every field still holding what it
sent, so the record's later values reach those; a field changed while the submission was in flight, or one whose
submission failed, stays an edit. An automatic form's submission does not end an edit: it goes out while the person
may still be typing, and loading the record's form of a number (`1.000` for a typed `1`) would change the text
under their cursor.
another record. A successful submission, automatic or explicit, ends the edit of every field still holding what it
sent, so the record's later values reach those; a field changed after the submission was sent, or one whose
submission failed, stays an edit. An automatic form submits while the person may still be typing, which two rules
make safe. First, the record's form of the value just sent does not load: a saved scalar takes the record's value
only when it would encode differently from the draft, so a typed `1` stays `1` when the record answers `1.000`
(the comparison is the encoded body entry, not the text). Second, the snapshot a success is judged against is the
one taken when that submission went out, so text typed while it was in flight is never mistaken for it, even when a
following submission starts in the same turn as the reply. The engine has no focus, so "still typing" is "changed
since the last send", which is exactly what the snapshots record. An automatic form's object and collection do not
end their edit on a save: their members and rows cannot be compared with the record without rebuilding them under
the cursor, so they own what was entered until the form is rebuilt or loaded with `prefill`. A member the record leaves out loads blank into a field that is no longer an edit, as it does in `prefill`.
- **Formatting follows the screen.** `setFormat(locale, datePattern, dateTimePattern)` on a `FormSession` (and so on a
`WizardSession`'s steps and a `CollectionSession`'s editor) replaces the number locale and the date patterns of a
built form. The number locale is read by every field's encoding, so each re-encodes its draft at once and the body
follows; the drafts keep the text as typed, so `1,5` typed under a comma locale reads as an error once the locale
switches to a point. The date inputs' `pattern` is read tracked and follows. The screen's interpreter keeps an effect per
form, collection and wizard that applies the session's current formatting, and holds the facts it applied, because the
number locale is a set of views into them. The display zone and the translations are read once, at build.
- **Choice options** are a `reactive::Query<std::string, std::string>` per Choice, keyed on the options request:
`{}` for an independent Choice, `{"parent": <literal>, …}` once every parent encodes, idle while one does not.
A parent change refetches, and a reply for a superseded request is dropped. A selection the answered options no
Expand Down Expand Up @@ -257,7 +270,7 @@ before it.
| Quantity | `TextInput` showing its unit, as a Decimal's (one unit); with alternatives, a `TextInput` with no unit and a unit `Select` beside it; switching converts the draft exactly |
| Boolean | `Checkbox` labelled with the field |
| Enum, Choice | `Select` (dropdown, or radio for `x-widget: radio`) keyed by each option's JSON literal; a Choice adds a `Busy` while its options load |
| DateTime, EpochDateTime; Date, EpochDate | `DateTimeInput` (date-time in the display zone; date); the input shows and reads `FormSessionOptions::datePattern` or `dateTimePattern` while they are set (`ScreenCore::engineOptions` fills them from the session's formatting), and the draft text stays ISO |
| DateTime, EpochDateTime; Date, EpochDate | `DateTimeInput` (date-time in the display zone; date); the input shows and reads `FormSessionOptions::datePattern` or `dateTimePattern` while they are set (`ScreenCore::engineOptions` fills them from the session's formatting), and the draft text stays ISO; the input follows `FormSession::setFormat`, which the screen calls whenever its formatting changes |
| Slider | `Slider` over `x-min`..`x-max` by `x-step` |
| Array | `TextInput`, comma-separated |
| Object | `Panel` of its members' cells |
Expand Down
Loading
Loading