entelechy-sessionGenerated

Layer: interface · Lines of code: 10,489 · Integration test files: 59

Brief

Entelechy session: a live scene over the runtimes, which every interface drives

Description

A live session over one .esn document and the libraries it uses.

The session reads its documents through entelechy-documents, which parses them, publishes their Kernels, follows their use items and lowers the Graph. Each Session::sync republishes only Kernels whose text changed; a rejected replacement leaves the running version.

The session opens the backends, keeps the runtime and evaluator, and orders the documents’ sync. What a caller observes is read from the parts it is handed.

Every interface (command line, Player, C ABI, importer, exporter) opens a Session. The wire is entelechy-protocol; file formats are entelechy-formats.


Internal dependencies	`entelechy-compiler`, `entelechy-cpu`, `entelechy-documents`, `entelechy-formats`, `entelechy-gpu`, `entelechy-graph`, `entelechy-ir`, `entelechy-jit`, `entelechy-kernel`, `entelechy-language`, `entelechy-rules`, `entelechy-scene`
External dependencies	—
Source	`crates/interface/session`

Modules

Name	Brief
`apart`	Rounding apart: a scene run with some of its Kernels rounding as another device might, to find a decision two Kernels must agree on and each makes for itself. Devices round an expression to different last bits in different Kernels, as their compilers fuse `a * b + c` into one rounding or take `a / b` as `a * (1 / b)`; a replay allows what that changes in a picture, so what fails when some Kernels round apart is a value two Kernels compute each and must hold equal. It is made in one (decision).
`bench`	Repeatable scene measurement: steps a scene for a frame count, several runs, on each named backend, and reports the best run.
`play`	The Player’s frame, device-free. Every interface that plays a scene hands its keys, pointer, wheel and pads here, asks for a frame, and shows the picture and plays the sound it names. This module owns the meaning of F5, Tab and F10, of F7, F8 and F9 (the scene’s clock held still and stepped a frame at a time), the pad mapping, the picture and sound choice, replay driving and the frame-data line.
`play::hud`	The F10 frame data, rendered on the CPU with a 5x7 font into `0x00RRGGBB` pixels for a presenter to overlay: a line of the frame’s times, then the nodes that kept the device busiest. Times come from the host’s clock, and the device’s own where it keeps one.
`play::pad`	A gamepad as a keyboard: buttons and the left stick press the keyboard’s key codes.
`preparing`	Kernels preparing as a scene reads them: an input `= progress` holds the Kernels the session watches and the scene they are for, as words (`words`), held again when they change. A session watches its own until the caller gives it another’s (`crate::Session::watch`).
`remember`	Preparing once: backends opened once for many sessions, each Kernel prepared on them once. A run of many replays of one scene opens a session each, fresh, its own runtime, Host and state, so no replay sees another’s; what they share is what preparing a Kernel makes of its IR (a device’s pipeline, the JIT’s machine code), which is the same for the same IR whichever session asks.
`replay`	Declarative replay: an application’s tests as data. A replay drives a scene through scripted frames and inputs and checks what they produce. Every form a line takes is in `docs/USAGE.md`, Replay tests, which `parse` is held to.
`watch`	Preparing seen from the terminal (the CLI’s commands, and the Player before its window opens): while a session’s Kernels take longer than a moment to prepare, a line of seeds, one for each Kernel (or a few where there are many), waiting `·`, compiled `•`, built `●` in gold, the ones building glowing; then how many are built and the one taking longest. Once they are, the line goes and one line says what it took. Where standard error is no terminal, only that last line is written.

Structs

Name	Brief
`apart::Apart`	A backend whose chosen Kernels are prepared rounding apart; the rest, and everything it runs, are its inner backend’s.
`bench::Options`	How to measure.
`bench::Measured`	What one backend measured.
`bench::Profile`	Each node’s time, placement and traffic over frames timed node by node (a session `Session::set_measured`): what `bench --nodes` reports, and `render` and `replay` under `--profile`.
`bench::NodeTime`	A node’s (or node pattern’s) time a frame and placement.
`play::hud::Panel`	The rendered line: `0x00RRGGBB` pixels, `width` per row.
`play::hud::Stats`	Smoothed frame times.
`play::pad::Pad`	Pad state beyond the input: which arrows the left stick holds.
`play::Reporting`	Deduplicates a run of failures: the first frame of a failure is reported, repeats that differ only in numbers are quiet, and the first working frame after them is reported.
`play::View`	The showing device’s state this frame.
`play::Shown`	A frame to show.
`play::Play`	A scene being played: input, preview, frame-data line, replay, and the last picture placement, which maps the pointer.
`remember::Remembered`	A backend that prepares a module equal to one it prepared before by handing out that preparation again. A refusal is not remembered.
`remember::Warm`	Backends opened once, and what was prepared on them, for many sessions one after another: each `Warm::runtime` is a runtime of its own over them.
`replay::Form`	One form a replay line takes, as `help` and `docs/USAGE.md` show it.
`replay::Replay`	A parsed replay file.
`replay::ReplayError`	A replay file does not parse.
`replay::Outcome`	What a replay run observed.
`replay::Changed`	What changed in a scene’s documents since its session last read them.
`replay::Resident`	Replays played one after another, each scene’s on one session kept for them all: a replay starts the world over (`Session::start_over`), so what it sees is what a fresh session would show it, while the Kernels stay compiled and prepared, the documents parsed, and the outputs no state feeds (a world baked from its seed) are spared. A document changed between replays is read again as a running session reads it. Rounded apart, each way keeps a session of its own.
`replay::Frame`	A frame a replay asks for: its context and what it must evaluate. A caller that shows the picture (a window) evaluates everything.
`replay::Replayer`	A replay played a frame at a time over a caller’s session: the steps between frames are applied, and the next frame is handed back for the caller to evaluate.
`watch::Watch`	Watches until dropped.
`Snapshot`	The world at one moment, taken for its caller to keep (`Session::snapshot`).
`StateCopy`	One port’s committed state in a snapshot.
`Traced`	A traced element: the trace, the Kernel it ran, and where its failure, if any, is written.
`Built`	A runtime built for a session (`Session::build`).
`Publishing`	A `publish` being prepared (`Session::publish_later`), finished by `Session::publishing`.
`Loaded`	A session opened and its scene read (`Session::open_loaded`).
`Limits`	What a session’s Host may hold and spend: Field words held at once (`--memory`), loop iterations one Kernel run may take across all its elements (`--work`), and the operations a run may take and go to the processor when the main backend is a device (`--small`).

Enumerations

Name	Brief
`play::pad::PadButton`	A pad’s button, by position.
`play::pad::PadAxis`	A pad’s analog axis; a stick’s up and right are positive.
`play::PointerLook`	What the pointer looks like over the window.
`play::Frame`	A frame’s result.
`replay::Step`	One scripted step.
`replay::Compare`	How an element expectation holds a value to what is written.
`Structure`	What structure a restored snapshot runs in.
`Laws`	What laws a restored snapshot runs under.
`SessionError`	Session-level failures.

Functions

Function	Brief
`fn chosen(id: &str, split: u32) -> bool`	Whether Kernel `id` rounds apart in split `split`: bit `split` of a hash of its id (FNV-1a), the same wherever it is asked.
`fn rounded_apart(module: &Validated) -> Result<(Validated, usize), String>`	`module` rounding as another device might: every float `a * b + c` fused into one `fma`, rounded once, and every float `a / b` taken as `a * (1 / b)`, rounded twice; and how many operations changed.
`fn bench(options: &Options) -> Result<Vec<Measured>, String>`	Measures every backend the options name.
`fn measure(session: &mut Session, backend: &str, frames: u32, repeat: u32, rate: f32, base: Context, nodes: bool) -> Result<Measured, String>`	Measures the session: a warm-up frame, `repeat` runs of `frames` frames, and, with `nodes`, one run timing every node. Time advances from `base` by frame count over `rate`, as `advance` does; the session is left at the last frame.
`fn table(options: &Options, measured: &[Measured], before: Option<&[Measured]>) -> String`	The measurement as a table: a line per backend, compared against the first, then node costs when measured.
`fn bytes_text(bytes: u64) -> String`	Bytes for reading: `512 B`, `1.5 KiB`, `3.2 MiB`.
`fn json(options: &Options, measured: &[Measured]) -> String`	The measurement as JSON, for `--compare` on a later build.
`fn read(path: &Path) -> Result<Vec<Measured>, String>`	Reads back the numbers a comparison needs from `--json` output; a malformed file is an error.
`fn panel(text: &str, scale: u32) -> Panel`	Renders `text` at `scale` device pixels per font pixel, uppercase as lowercase; a character outside the font is a gap.
`fn lines(texts: &[String], scale: u32) -> Panel`	Renders `texts`, a line each, one under another, as `panel` does.
`fn lines_at_least(texts: &[String], scale: u32, columns: usize) -> Panel`	`lines`, the panel at least `columns` wide.
`fn stamp(panel: &Panel, frame: &mut [u32], frame_width: u32, frame_height: u32)`	Stamps the panel into the top-left of a `0x00RRGGBB` frame, clipped.
`fn flow(groups: &[String], columns: usize) -> Vec<String>`	Groups laid left to right, `\|` between them, a line taking as many as fit in `columns`; a group is never broken.
`fn to_output(placement: &Placement, window_x: f32, window_y: f32, width: u32, height: u32) -> [f32; 2]`	Maps a window position to output pixel coordinates; positions in the letterbox clamp to the nearest edge.
`fn present(pixels: &[[f32; 4]], width: u32, height: u32, target_width: u32, target_height: u32, frame: &mut [u32]) -> Placement`	CPU presentation: converts linear float pixels to `0x00RRGGBB`, scales them nearest-neighbor into the target frame at their aspect ratio, letterboxes with black, and returns the placement.
`fn key_code(name: &str) -> Option<i32>`	The browser’s code for a key, by the key’s name or the character it typed (`key()` reads these; its help lists them): a letter or a digit by its ASCII uppercase, a character typed with shift by the key under it on a US keyboard, or a listed named key.
`fn words(now: &Preparing) -> Vec<u32>`	`now` as words: the nodes’ count, the links’ count, the Kernels’ count, how many are built, 1 while any waits or runs (else 0), and the milliseconds of the step running longest; then each node’s stage (0 waiting, 1 compiling, 2 compiled, 3 building, 4 built; a node whose Kernel is not being prepared is built); then each link’s two nodes, by place; then the name of the Kernel running longest, a character a word, and a 0.
`fn forms() -> Vec<Form>`	Every form a replay line takes, in the order a replay uses them.
`fn forms_table() -> String`	The forms as `docs/USAGE.md` shows them.
`fn parse(text: &str, base: &Path) -> Result<Replay, ReplayError>`	Parses replay text; relative paths resolve against `base`.
`fn run(replay: &Replay, runtime: Runtime) -> Result<Outcome, String>`	Runs a replay on a fresh session over `runtime`, each frame evaluating only what its expectations need.
`fn run_in(replay: &Replay, store: Arc<dyn Store>, runtime: Runtime) -> Result<Outcome, String>`	`run`, reading documents from `store`.
`fn run_fused(replay: &Replay, store: Arc<dyn Store>, runtime: Runtime, fusion: bool) -> Result<Outcome, String>`	`run_in`, fusing pointwise producers into their consumers or not.
`fn run_each(replay: &Replay, store: Arc<dyn Store>, runtime: Runtime, fusion: bool, each: Option<&mut Each<'_>>) -> Result<Outcome, String>`	`run_fused`, handing each evaluated frame to `each`.
`fn store_for(replay: &Replay, store: Arc<dyn Store>) -> Arc<dyn Store>`	The store a replay’s session reads and writes: `store`, or, where the replay allows its outputs to write, `store` with every write kept beside it (`crate::Kept`): a run changes nothing on disk, and every run starts from the same files.
`fn allow_on(replay: &Replay, session: &mut Session) -> Result<(), String>`	Gives `session` what `replay` allows (`Replay::allowed`).
`fn clear()`	Takes the line of seeds away, so what is written next has its own line; drawn again while preparing goes on.
`fn watch(progress: Progress) -> Watch`	Watches `progress` on a thread of its own.
`fn preparing_lines(now: &Preparing) -> Vec<String>`	Each Kernel’s last preparing, the longest first: under a heading, its compiling and its building in milliseconds, then its id; then their sums. Nothing where no Kernel was prepared.
`fn parse_window(text: &str) -> Result<([f32; 2], f32), String>`	Parses a window given on a command line: `<w>x<h>` or `<w>x<h>@<scale>`, returning the size in pixels and the scale factor (one when absent).
`fn budget_of_megabytes(megabytes: usize) -> usize`	The words in a number of mebibytes, which is how `--memory` asks.

Constants

Name	Type	Value	Brief
`apart::SPLITS`	`u32`	`3`	The ways of choosing which Kernels round apart: a run each.
`play::hud::HELD_FOR`	`f64`	`0.25`	Seconds the shown lines are held before they are made again.
`play::STEP`	`f64`	`_`	How far one step moves the scene’s held time, in seconds: a frame at sixty a second.
`preparing::HEAD`	`usize`	`6`	The words before the nodes’ stages.
`POINTER_MOST`	`u32`	`128`	The most pixels a side of the pointer’s picture may have: what a browser takes for a page’s pointer.
`DEFAULT_BUDGET_WORDS`	`usize`	`_`	The default word budget of a session’s Host: two gibibytes. It is a net that stops a runaway scene before the machine swaps; `--memory` raises it.

Type aliases

Name	Type	Brief
`replay::Each`	`dyn FnMut(&mut Session, &Report) -> Result<(), String>`	What a replay run hands each frame it evaluates, once evaluated: the session and the frame’s report. A run that hands its frames on evaluates the scene’s outputs every frame.

Re-exports

Placement, placement, Pad, PadAxis, PadButton, Attempt, Change, Origin, Record, Arrived, Disk, FetchFn, FetchLaterFn, Kept, Later, Memory, Parsed, Store, Allowance, Diagnostic, Event, Fix, Refusal, SourcePlace, history, overrides, package, parse_allow, store, Wait, SessionOptions, environment_packages, DeviceTimes, HeldBytes, MemoryMap, Warm, Session, Declarations, PACKAGE_VERSION, declarations_for, declarations_within, locate_document, package_manifest, read_document, used_documents, parse_target, CALL_RECORDS, Trace, TraceFault, TraceValue, Clipboard, Held, Checked, LARGE, check_document, check_document_with, large, large_past

apart::Apart

crates/interface/session/src/apart.rs#L163

A backend whose chosen Kernels are prepared rounding apart; the rest, and everything it runs, are its inner backend’s.

Methods

Function	Description
`fn new(inner: Box<dyn Backend>, split: u32) -> Self`	`inner`, the Kernels `chosen` by `split` rounding apart.
`fn changed(&self) -> usize`	How many operations the Kernels prepared so far round apart.

Implemented traits: Backend

bench::Options

crates/interface/session/src/bench.rs#L18

How to measure.

Properties

Name	Type	Description
`session`	`SessionOptions`	The session each backend opens; `backends` overrides its backend.
`backends`	`Vec<String>`	Backends to measure, in order.
`frames`	`u32`	Frames in a run, after the warm-up frame.
`repeat`	`u32`	Runs of that many frames.
`rate`	`f32`	Frames per second the clock advances by.
`window`	`Option<([f32; 2], f32)>`	Window size and scale for `window()`.
`nodes`	`bool`	Whether to measure each node as well as the frame.
`json`	`Option<PathBuf>`	Where to write the measurement as JSON.
`compare`	`Option<PathBuf>`	A measurement to compare against.

Implemented traits: Clone, Debug, Default

bench::Measured

crates/interface/session/src/bench.rs#L57

What one backend measured.

Properties

Name	Type	Description
`backend`	`String`	The backend measured.
`best`	`f64`	Milliseconds a frame in the best run.
`median`	`f64`	Milliseconds a frame in the median run.
`first`	`f64`	Milliseconds the first frame took, which the runs leave out: the work done once, compiling, building, filling what is kept.
`wait`	`f64`	Milliseconds a frame of the best run’s the frame’s thread waited for the device; the rest of the frame is its own work.
`waits`	`Vec<(String, f64)>`	Each node that kept the frame’s thread waiting for the device in the best run, milliseconds a frame, longest first.
`wait_after`	`f64`	Milliseconds a frame of the best run waited for the device that no node did: at the frame’s end, confirming the frame before, writing.
`gpu`	`Option<f64>`	With nodes, the device’s busy time a frame by its own clock, where it keeps one.
`nodes`	`Vec<NodeTime>`	Each node’s milliseconds a frame, when asked for, averaged over all frames.
`ran`	`bool`	Whether any node ran after the warm-up frame.
`device_clock`	`bool`	Whether node times come from the device’s clock; otherwise they are the call and its wait, less `floor`.
`floor`	`f64`	Milliseconds one empty node measurement costs, already subtracted from every node time.
`refused`	`Vec<String>`	Groups the backend refused to run fused, which ran apart.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

bench::Profile

crates/interface/session/src/bench.rs#L356

Each node’s time, placement and traffic over frames timed node by node (a session Session::set_measured): what bench --nodes reports, and render and replay under --profile.

Methods

Function	Description
`fn add(&mut self, report: &Report)`	Adds a frame’s report: each node it ran.
`fn frames(&self) -> u32`	How many frames were added.
`fn nodes(&self, floor: f64) -> Vec<NodeTime>`	Each node’s milliseconds a frame (over every frame added, a frame that reused it counting none), less `floor` (what measuring one node costs before it does anything); repeated placements grouped into one line, `steps/.spread/` and their count; the busiest first.
`fn lines(&self, floor: f64, device_clock: bool) -> Vec<String>`	The profile as lines: a heading saying how the nodes were timed (`device_clock`, `floor`), each node’s line, their sum.

Implemented traits: Default

bench::NodeTime

crates/interface/session/src/bench.rs#L649

A node’s (or node pattern’s) time a frame and placement.

Properties

Name	Type	Description
`node`	`String`	The node, or its pattern and count.
`ms`	`f64`	Milliseconds a frame: on its device by the device’s clock, or on the processor.
`call`	`f64`	Milliseconds a frame on the frame’s thread, giving its runs to the device or running them; the same as `ms` for a processor’s node.
`backend`	`String`	The backend that ran it.
`routed`	`Option<String>`	Why it was routed off the main backend, if it was.
`uploaded`	`u64`	Bytes a frame uploaded from Host memory to a device.
`downloaded`	`u64`	Bytes a frame downloaded back to Host memory.

Methods

Function	Description
`fn placement_text(&self) -> String`	A profile line’s tail: backend, routing reason, traffic.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

play::hud::Panel

crates/interface/session/src/play/hud.rs#L71

The rendered line: 0x00RRGGBB pixels, width per row.

Properties

Name	Type	Description
`width`	`u32`	Width in pixels.
`height`	`u32`	Height in pixels.
`pixels`	`Vec<u32>`	The pixels, row by row.

Implemented traits: Clone, Debug, Default, Eq, PartialEq, StructuralPartialEq

play::hud::Stats

crates/interface/session/src/play/hud.rs#L146

Smoothed frame times.

Methods

Function	Description
`fn begin(&mut self, now: f64)`	Marks a frame’s start; the time since the last one is its interval.
`fn record(&mut self, cpu: Duration, gpu: Option<Duration>)`	Records a frame’s processor time and the device’s busy time on the latest frame it has done.
`fn waited(&mut self, total: Duration, by: &[(NodeId, Duration)])`	Records how long a frame’s thread waited for the device in all, and which nodes waited (`entelechy_graph::Report::waits`); what no node waited is the frame’s end. Shown as `Stats::told` shows.
`fn waiting(&self, most: usize) -> Vec<String>`	The nodes that kept the frame’s thread waiting longest for the device, `most` of them, then the waits at the frame’s end; the first headed `waited for the device:`. None while nothing waits.
`fn told(&mut self, times: &DeviceTimes)`	Records a clocked frame’s device time node by node, once a frame: a node not in it is taken as idle. The first frame is shown at once, then each `SHOWN_EVERY` frames’ average.
`fn busiest(&self, most: usize) -> Vec<String>`	The nodes that kept the device busiest, `most` of them, each `name ms` with its milliseconds in a fixed width, then what ran between nodes; the first headed `gpu by node:`.
`fn held(&mut self, make: impl FnOnce(&Self) -> Vec<String>) -> Vec<String>`	`make`’s lines, made again only `HELD_FOR` seconds after the last were.
`fn widest(&self) -> usize`	The most columns a shown line has taken.
`fn presented(&mut self, present: Duration)`	Records this frame’s presenting time.
`fn times(&self) -> String`	The smoothed times, each number in a fixed width.

Implemented traits: Debug, Default

play::pad::Pad

crates/interface/session/src/play/pad.rs#L114

Pad state beyond the input: which arrows the left stick holds.

Methods

Function	Description
`fn button(&mut self, input: &mut InputState, button: PadButton, down: bool)`	A button pressed or released.
`fn axis(&mut self, input: &mut InputState, axis: PadAxis, value: f32)`	An axis moved to `value`.

Implemented traits: Clone, Copy, Debug, Default

play::Reporting

crates/interface/session/src/play/mod.rs#L25

Deduplicates a run of failures: the first frame of a failure is reported, repeats that differ only in numbers are quiet, and the first working frame after them is reported.

Methods

Function	Description
`fn failed(&mut self, message: &str) -> bool`	Whether this failure is new: its shape differs from the current.
`fn worked(&mut self) -> bool`	Whether a working frame ends a run of failures.

Implemented traits: Default

play::View

crates/interface/session/src/play/mod.rs#L179

The showing device’s state this frame.

Properties

Name	Type	Description
`window`	`[f32; 2]`	Window size in physical pixels; zero before a window exists.
`scale`	`f32`	Scale factor.
`rate`	`f32`	Sound sample rate; zero without a sound device.
`queued`	`u32`	The samples (per channel) the sound device holds and has not yet played (`queued()`); zero without one.

Implemented traits: Clone, Copy, Debug

play::Shown

crates/interface/session/src/play/mod.rs#L192

A frame to show.

Properties

Name	Type	Description
`report`	`Report`	The evaluation’s report.
`picture`	`Handle`	The picture: the graph’s, or the node F6 previews.
`sound`	`Option<Handle>`	The sound output, if any.

play::Play

crates/interface/session/src/play/mod.rs#L285

A scene being played: input, preview, frame-data line, replay, and the last picture placement, which maps the pointer.

Methods

Function	Description
`fn new(clock: fn() -> f64) -> Self`	A play timed by `clock`, the host’s clock in seconds.
`fn replay(&mut self, replay: &Replay, session: &mut Session)`	Plays `replay`: its inputs drive the scene at its times until it ends; then the person does.
`fn replaying(&self) -> bool`	Whether a replay is playing.
`fn time(&self) -> f64`	The scene’s time: seconds since the play began, less the time it was paused; while paused, the time it is held at.
`fn paused(&self) -> bool`	Whether the scene’s time is held still.
`fn pause(&mut self, paused: bool)`	Holds the scene’s time still, or lets it run on from where it was held. Frames go on while it is held: what the scene draws from its time stands still, and it still takes the person’s input; a scene that steps every frame without reading its time steps on.
`fn step(&mut self, frames: i32)`	Moves the held time `frames` steps of `STEP` (back when below zero, never before the start), pausing first if it was running.
`fn context(&self, view: View) -> Context`	The context of the person’s frame on `view`.
`fn key(&mut self, session: &mut Session, name: &str, down: bool)`	A key by name (`a`, `ArrowLeft`, `F5`). F5 resets state, F6 moves the preview, F10 toggles the frame-data line; F8 holds the scene’s time still or lets it run, F9 steps it a frame on and F7 a frame back (while a replay plays, its inputs keep the time). Every other key goes to the scene, Tab and Escape among them.
`fn release_keys(&mut self)`	Every key let go: the window lost the focus, and the releases of the keys held go to whatever has it.
`fn modifiers(&mut self, shift: bool, control: bool, alt: bool, command: bool)`	The modifier keys the system says are held: Shift, Control, Alt and Command (or Windows) that are not are let go, whichever window their release went to.
`fn pointer(&mut self, x: f32, y: f32)`	The pointer at `(x, y)` in window pixels.
`fn button(&mut self, which: u8, down: bool)`	A pointer button, 0 left, 1 right, 2 middle.
`fn typed(&mut self, text: &str)`	Characters typed (a key’s text, or what an input method commits), what `typed()` reads: the next frame takes as many as it holds, the frames after the rest. Control characters (Enter, Tab, Backspace) and the private codes some systems give arrows and function keys are keys, which `key()` reads, not characters.
`fn wheel(&mut self, x: f32, y: f32)`	Wheel lines, y positive away from the person; accumulated until the next frame.
`fn pad_button(&mut self, button: PadButton, down: bool)`	A pad’s button. A pad’s contacts chatter: a release is held back `PAD_SETTLE`, and a press within it was the button held.
`fn pad_axis(&mut self, axis: PadAxis, value: f32)`	A pad’s axis.
`fn pads_connected(&mut self, count: u32)`	How many pads are connected, what `pads()` reads.
`fn sound_opened(&mut self, description: impl Into<String>)`	Records the opened sound device’s description.
`fn frame(&mut self, session: &mut Session, view: View) -> Frame`	One frame: syncs disk changes (every `SYNC_EVERY` seconds, every frame while a replay plays), takes a due replay frame, evaluates, and names the picture and sound.
`fn confirm(&mut self, session: &mut Session) -> bool`	Confirms the frame in flight before something other than the next frame reads the session (a request); a failed one is said as a failed frame is. Whether it was confirmed.
`fn heard(&mut self, session: &mut Session, sound: Handle) -> Option<Vec<u32>>`	The sound to hear now, as words, `sound` being the frame’s sound output (`Shown::sound`). Overlapping, it is the frame before’s, confirmed by now and fetched behind its own work alone, while this frame’s is fetched for the next: hearing never waits for the frame just made. Otherwise this frame’s, brought back now.
`fn pointer_look(&mut self, session: &mut Session, report: &Report) -> Option<PointerLook>`	The pointer’s look when it differs from the one an interface was last told, `report` being the frame’s (`Shown::report`); `None` when it is the same. The scene’s picture and hotspot are read only when one of their Fields is a new one: overlapping, they are fetched behind the frame’s own work and looked at the frame after, as the sound is heard.
`fn placed(&mut self, placement: Option<Placement>, size: (u32, u32), path: &str, downloaded: bool, presenting: f64)`	Records how the device showed the picture: placement (`None`: unchanged), size, path (`presented on the device`, `downloaded and blitted`), whether it downloaded, and seconds taken.
`fn landed(&mut self, placement: Option<Placement>, size: (u32, u32))`	Records the picture’s placement (`None`: unchanged) and size, which map the pointer.
`fn panel(&self) -> Option<&Panel>`	The frame-data line, when F10 shows it.
`fn status(&self) -> &str`	`running`, a replay’s time, or the failure that kept the last picture.
`fn say(&mut self, line: String)`	Adds a line from the interface, such as a skipped backend.
`fn said(&mut self) -> Vec<String>`	Lines since the last call: events, failures, the preview, a replay’s outcome.
`fn showing(&self, report: &Report, shown: Handle) -> String`	What the window shows, as the line of frame data names it: the previewed node’s port, or the scene output `shown` is.

remember::Remembered

crates/interface/session/src/remember.rs#L46

A backend that prepares a module equal to one it prepared before by handing out that preparation again. A refusal is not remembered.

Implemented traits: Backend

remember::Warm

crates/interface/session/src/remember.rs#L216

Backends opened once, and what was prepared on them, for many sessions one after another: each Warm::runtime is a runtime of its own over them.

Methods

Function	Description
`fn runtime(&self) -> Runtime`	A runtime of its own over the backends, preparing each module once across every runtime given.
`fn runtime_apart(&self, split: u32) -> Runtime`	`Warm::runtime` with the Kernels `crate::apart::chosen` by `split` rounding apart (`crate::apart`): a module rounded apart is prepared once too, whichever runtime asks.
`fn open(backend: &str, limits: Limits) -> Result<Self, String>`	Opens `backend` (`cpu`, `gpu` or `jit`) once, for many sessions.

replay::Form

crates/interface/session/src/replay.rs#L16

One form a replay line takes, as help and docs/USAGE.md show it.

Properties

Name	Type	Description
`keyword`	`&'static str`	The line’s first word.
`shape`	`&'static str`	Its shape: `<...>` a value, `[...]` optional, `\|` a choice.
`doc`	`&'static str`	What it does.
`examples`	`&'static [&'static str]`	Lines written in it, each one the parser reads.

Implemented traits: Clone, Debug

replay::Replay

crates/interface/session/src/replay.rs#L339

A parsed replay file.

Properties

Name	Type	Description
`scene`	`PathBuf`	Scene path, resolved.
`kernels`	`Option<PathBuf>`	Kernel directory, resolved, if given.
`steps`	`Vec<Step>`	Steps in order.
`allowed`	`Vec<Allowance>`	The directories its scene’s outputs may write files in, or remove and rename them in, resolved (`store_for`).
`alike`	`bool`	Whether its checks hold two forms of one computation equal word for word: `--round-apart` leaves it out.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

replay::ReplayError

crates/interface/session/src/replay.rs#L356

A replay file does not parse.

Properties

Name	Type	Description
`line`	`u32`	1-based line.
`message`	`String`	What is wrong.

Implemented traits: Clone, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

replay::Outcome

crates/interface/session/src/replay.rs#L680

What a replay run observed.

Properties

Name	Type	Description
`frames`	`usize`	Frames evaluated.
`checks`	`usize`	Expectations checked.
`failures`	`Vec<String>`	Expectations that failed, as messages.
`shown`	`Vec<String>`	What `show` steps printed, in order.
`refused`	`Vec<String>`	Groups the backend refused to run fused, each said once.
`touched`	`BTreeSet<String>`	The nodes its outcome depends on: what its frames asked for, and every node those read, now or as committed state, by the graph, whether a frame ran them or spared them as unchanged.

Methods

Function	Description
`fn lines(&self) -> Vec<String>`	The report of a run: the groups refused fused, the shown values, then the failures, each a line under the replay’s own.

Implemented traits: Clone, Debug, Default, PartialEq, StructuralPartialEq

replay::Changed

crates/interface/session/src/replay.rs#L875

What changed in a scene’s documents since its session last read them.

Properties

Name	Type	Description
`whole`	`bool`	The graph itself changed, or a document was refused: every replay of the scene plays again.
`kernels`	`BTreeSet<String>`	The Kernels published again or retired.
`inputs`	`BTreeSet<String>`	The inputs read again.
`said`	`Vec<String>`	What the sync said, to show.

Implemented traits: Clone, Debug, Default

replay::Resident

crates/interface/session/src/replay.rs#L895

Replays played one after another, each scene’s on one session kept for them all: a replay starts the world over (Session::start_over), so what it sees is what a fresh session would show it, while the Kernels stay compiled and prepared, the documents parsed, and the outputs no state feeds (a world baked from its seed) are spared. A document changed between replays is read again as a running session reads it. Rounded apart, each way keeps a session of its own.

Methods

Function	Description
`fn new(warm: Warm, store: Arc<dyn Store>, fusion: bool) -> Self`	Over backends opened once and documents read through `store`.
`fn play(&mut self, replay: &Replay, split: Option<u32>) -> Result<Outcome, String>`	Plays `replay` on its scene’s session, rounding apart in `split` when one is given (`crate::apart`).
`fn play_as(&mut self, name: Option<&str>, replay: &Replay, split: Option<u32>) -> Result<Outcome, String>`	`Resident::play`, remembering the run as `name`: played again under that name, each frame takes from the same frame of this run what nothing it reads has changed (`Session::recall_as`).
`fn changed(&mut self) -> HashMap<PathBuf, Changed>`	Reads every kept session’s documents again, saying per scene what changed (`Changed`). A graph rebuilt the same is no change of its own: what changed is what its Kernels and inputs say.
`fn affects(&self, changed: &HashMap<PathBuf, Changed>, scene: &Path, touched: &BTreeSet<String>) -> bool`	Whether what changed reaches a replay of `scene` that touched `touched`: a node it touched runs a Kernel published again or retired, or reads an input read again.
`fn watched(&self) -> Vec<PathBuf>`	The documents and files every kept session reads, to watch.

replay::Frame

crates/interface/session/src/replay.rs#L1072

A frame a replay asks for: its context and what it must evaluate. A caller that shows the picture (a window) evaluates everything.

Properties

Name	Type	Description
`context`	`Context`	The time, input and window of this frame.
`demand`	`BTreeSet<NodeId>`	The named nodes, and the picture when a pixel expectation follows.

replay::Replayer

crates/interface/session/src/replay.rs#L1082

A replay played a frame at a time over a caller’s session: the steps between frames are applied, and the next frame is handed back for the caller to evaluate.

Properties

Name	Type	Description
`outcome`	`Outcome`	What the replay has observed so far.

Methods

Function	Description
`fn start(replay: &Replay, session: &mut Session) -> Self`	Starts `replay` over a synced `session`, pinning the nodes the expectations name.
`fn next_time(&self) -> Option<f64>`	The time of the next frame, when there is one.
`fn finished(&self) -> bool`	Whether every step has been applied.
`fn next_frame(&mut self, session: &mut Session) -> Result<Option<Frame>, String>`	Applies the steps up to the next frame and returns it; `None` once every step is applied. Expectations read the report given to `Replayer::evaluated`.
`fn evaluated(&mut self, report: Report)`	Takes the report of the frame `Replayer::next_frame` handed back.

watch::Watch

crates/interface/session/src/watch.rs#L42

Watches until dropped.

Implemented traits: Drop

Snapshot

crates/interface/session/src/lib.rs#L53

The world at one moment, taken for its caller to keep (Session::snapshot).

Properties

Name	Type	Description
`revision`	`u64`	The revision it was taken at.
`frame`	`u64`	The frames the revision had run.
`laws`	`Vec<(KernelId, Generation, String)>`	Every published Kernel: id, generation and source, readable without the session.
`states`	`Vec<StateCopy>`	Every port’s committed state.
`scene`	`Option<String>`	The scene document the running graph was built from, if any.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

StateCopy

crates/interface/session/src/lib.rs#L88

One port’s committed state in a snapshot.

Properties

Name	Type	Description
`node`	`String`	The producing node.
`port`	`String`	Its port.
`schema`	`Schema`	The element layout.
`domain`	`Domain`	The extent.
`words`	`Vec<u32>`	The Kernel’s words, one per scalar.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Traced

crates/interface/session/src/lib.rs#L118

A traced element: the trace, the Kernel it ran, and where its failure, if any, is written.

Properties

Name	Type	Description
`trace`	`Trace`	What the interpreter recorded.
`module`	`Validated`	The module it ran: the trace’s types name its structs.
`kernel`	`KernelId`	The node’s Kernel.
`place`	`Option<SourcePlace>`	Where the element’s failure is written, when it failed and a document owns the Kernel.

Implemented traits: Clone, Debug

Built

crates/interface/session/src/lib.rs#L137

A runtime built for a session (Session::build).

Properties

Name	Type	Description
`runtime`	`Runtime`	The runtime.
`display`	`Option<Display>`	The device’s display, when the backend has one.
`passed_over`	`Vec<String>`	The backends tried first and passed over, as `name: why`.

Publishing

crates/interface/session/src/lib.rs#L148

A publish being prepared (Session::publish_later), finished by Session::publishing.

Loaded

crates/interface/session/src/lib.rs#L155

A session opened and its scene read (Session::open_loaded).

Properties

Name	Type	Description
`session`	`Session`	The session, its scene loaded.
`display`	`Option<Display>`	The device’s display, when the backend has one.
`events`	`Vec<Event>`	What reading the scene said.
`passed_over`	`Vec<String>`	The backends tried first and passed over, as `name: why`.

Limits

crates/interface/session/src/lib.rs#L212

What a session’s Host may hold and spend: Field words held at once (--memory), loop iterations one Kernel run may take across all its elements (--work), and the operations a run may take and go to the processor when the main backend is a device (--small).

Properties

Name	Type	Description
`words`	`usize`	Words the Host may hold at once.
`work`	`u64`	Loop iterations one run may take.
`small`	`u64`	Operations a run may take, by its elements and its Kernel’s typical work, and go to the ordered backend; zero keeps every run on the main one.

Methods

Function	Description
`fn takes(flag: &str) -> bool`	Whether `flag` sets a limit: `--memory`, `--work` or `--small`.
`fn read(&mut self, flag: &str, text: &str) -> Result<(), String>`	Sets the limit `flag` names from its value: `--memory <MB>` in whole mebibytes, `--work <M>` in millions of iterations, `--small <operations>` in operations, zero allowed.

Implemented traits: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

play::pad::PadButton

crates/interface/session/src/play/pad.rs#L22

A pad’s button, by position.

Variants

Name	Description
`South`	Bottom face button (A, Cross).
`East`	Right face button (B, Circle).
`West`	Left face button (X, Square).
`North`	Top face button (Y, Triangle).
`LeftShoulder`	Left shoulder.
`RightShoulder`	Right shoulder.
`LeftThumb`	Left stick pressed.
`RightThumb`	Right stick pressed.
`Start`	Start.
`Select`	Select.
`Left`	D-pad left.
`Up`	D-pad up.
`Right`	D-pad right.
`Down`	D-pad down.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

play::pad::PadAxis

crates/interface/session/src/play/pad.rs#L55

A pad’s analog axis; a stick’s up and right are positive.

Variants

Name	Description
`LeftX`	Left stick, horizontal.
`LeftY`	Left stick, vertical.
`RightX`	Right stick, horizontal.
`RightY`	Right stick, vertical.
`LeftTrigger`	Left trigger, 0 released to 1 pulled.
`RightTrigger`	Right trigger.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

play::PointerLook

crates/interface/session/src/play/mod.rs#L203

What the pointer looks like over the window.

Variants

Name	Description
`System`	The system’s own pointer.
`Picture { width: u32, height: u32, rgba: Vec<u8>, hotspot: (u32, u32) }`	The picture the scene gives `to pointer`: its size, its pixels as 8-bit RGBA from the top row down, and the point it points with (what it gives `to pointer_tip`, else its middle).

Methods

Function	Description
`fn of(image: &Image, hotspot: Option<[f32; 2]>) -> Result<Self, String>`	The pointer `image` is, pointing with `hotspot` (pixels across and down from its top left, held inside it; its middle when `None`), or why it cannot be one.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

play::Frame

crates/interface/session/src/play/mod.rs#L273

A frame’s result.

Variants

Name	Description
`Wait`	A replay’s next frame is not due; nothing was evaluated.
`Shown(Box<Shown>)`	A frame to show.
`Failed`	The evaluation failed; the last picture stays, and `Play::status` says why.

replay::Step

crates/interface/session/src/replay.rs#L204

One scripted step.

Variants

Name	Description
`Frame(f64)`	Evaluate at a session time, in seconds.
`Settle`	Wait for every `async` node’s run to land.
`Pointer { position: Option<[f32; 2]>, down: bool }`	Move the pointer and set the button.
`Key { code: i32, down: bool }`	Press or release a key code.
`Button { code: i32, down: bool }`	Press or release a pointer button by number: 0 left, 1 right, 2 middle.
`Wheel([f32; 2])`	What the wheel scrolls for the next frame.
`Type(String)`	Characters typed, for the next frames to read with `typed()`, as many a frame as one holds.
`Clipboard(String)`	The clipboard’s text from here on.
`Stick { which: i32, at: [f32; 2] }`	A pad’s axis pair: 0 left stick, 1 right stick, 2 triggers.
`Pads(u32)`	How many pads are connected from here on.
`Window { size: [f32; 2], scale: f32 }`	The window’s size in pixels and its scale factor from here on.
`Reset`	Forget committed state.
`ResetPort { node: String, port: String }`	Forget one port’s committed state.
`Param { name: String, value: Value }`	Override a graph parameter.
`ExpectElement { node: String, port: String, index: u32, path: Vec<String>, compare: Compare, values: Vec<String>, line: u32 }`	Check a field of an element of a node’s output after the last frame.
`Show { node: String, port: String, index: u32, path: Vec<String>, line: u32 }`	Print an element of a node’s output after the last frame, or a field of it.
`ExpectCount { node: String, port: String, count: usize, line: u32 }`	Check how many elements a node’s output holds after the last frame.
`ExpectPlaced { node: String, routed: bool, line: u32 }`	Check where a node runs: the main backend, or the ordered one. Without an ordered backend (CPU, JIT), `ordered` checks as `main`.
`Expect { x: u32, y: u32, rgb: [f32; 3], tolerance: f32, line: u32 }`	Check a pixel of the last frame.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

replay::Compare

crates/interface/session/src/replay.rs#L1386

How an element expectation holds a value to what is written.

Variants

Name	Description
`Equal`	`=`: equal, a float within the tolerance.
`Below`	`<`: every component below.
`AtMost`	`<=`: every component at most.
`Above`	`>`: every component above.
`AtLeast`	`>=`: every component at least.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

Structure

crates/interface/session/src/lib.rs#L69

What structure a restored snapshot runs in.

Variants

Name	Description
`Current`	The scene as it stands.
`Snapshot`	The snapshot’s scene document, written back first.

Implemented traits: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

Laws

crates/interface/session/src/lib.rs#L79

What laws a restored snapshot runs under.

Variants

Name	Description
`Current`	The running laws; state migrates where a layout changed.
`Snapshot`	The snapshot’s own Kernels, published back.

Implemented traits: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

SessionError

crates/interface/session/src/lib.rs#L273

Session-level failures.

Variants

Name	Description
`Io(PathBuf, Error)`	A file could not be read or written.
`Image(PathBuf, PpmError)`	An external image could not be imported or the output exported.
`NoScene`	No scene has been loaded successfully.
`Host(HostError)`	The Host rejected an import.
`Observe(String)`	A resident image could not be brought back for observation.
`Unwritable(PathBuf, String)`	The file’s extension names no format that takes the Field.

Implemented traits: Debug, Display, Error