entelechy-session自动生成

本页由源码自动生成

数据来自 cargo +nightly doc --output-format json。下方的详细描述保留源码中的英文原文。

层：接口层 · 代码行数：10,489 · 集成测试文件：59

简述

会话：运行时之上的实时场景，所有界面都驱动它。

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

描述

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.

内部依赖	entelechy-compiler, entelechy-cpu, entelechy-documents, entelechy-formats, entelechy-gpu, entelechy-graph, entelechy-ir, entelechy-jit, entelechy-kernel, entelechy-language, entelechy-rules, entelechy-scene
外部依赖	—
源码	crates/interface/session

模块

名称	简述
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.

结构体

名称	简述
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).

枚举

名称	简述
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.

函数

函数	简述
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.

常量

名称	类型	取值	简述
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.

类型别名

名称	类型	简述
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.

重导出

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.

方法

函数	说明
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.

实现的 Trait: Backend

---

bench::Options

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

How to measure.

属性

名称	类型	说明
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.

实现的 Trait: Clone, Debug, Default

---

bench::Measured

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

What one backend measured.

属性

名称	类型	说明
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.

实现的 Trait: 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.

方法

函数	说明
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.

实现的 Trait: Default

---

bench::NodeTime

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

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

属性

名称	类型	说明
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.

方法

函数	说明
fn placement_text(&self) -> String	A profile line’s tail: backend, routing reason, traffic.

实现的 Trait: Clone, Debug, PartialEq, StructuralPartialEq

---

play::hud::Panel

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

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

属性

名称	类型	说明
width	u32	Width in pixels.
height	u32	Height in pixels.
pixels	Vec<u32>	The pixels, row by row.

实现的 Trait: Clone, Debug, Default, Eq, PartialEq, StructuralPartialEq

---

play::hud::Stats

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

Smoothed frame times.

方法

函数	说明
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.

实现的 Trait: Debug, Default

---

play::pad::Pad

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

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

方法

函数	说明
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.

实现的 Trait: 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.

方法

函数	说明
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.

实现的 Trait: Default

---

play::View

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

The showing device’s state this frame.

属性

名称	类型	说明
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.

实现的 Trait: Clone, Copy, Debug

---

play::Shown

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

A frame to show.

属性

名称	类型	说明
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.

方法

函数	说明
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.

实现的 Trait: 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.

方法

函数	说明
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.

属性

名称	类型	说明
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.

实现的 Trait: Clone, Debug

---

replay::Replay

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

A parsed replay file.

属性

名称	类型	说明
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.

实现的 Trait: Clone, Debug, PartialEq, StructuralPartialEq

---

replay::ReplayError

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

A replay file does not parse.

属性

名称	类型	说明
line	u32	1-based line.
message	String	What is wrong.

实现的 Trait: Clone, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

---

replay::Outcome

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

What a replay run observed.

属性

名称	类型	说明
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.

方法

函数	说明
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.

实现的 Trait: 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.

属性

名称	类型	说明
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.

实现的 Trait: 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.

方法

函数	说明
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.

属性

名称	类型	说明
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.

属性

名称	类型	说明
outcome	Outcome	What the replay has observed so far.

方法

函数	说明
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.

实现的 Trait: Drop

---

Snapshot

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

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

属性

名称	类型	说明
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.

实现的 Trait: Clone, Debug, PartialEq, StructuralPartialEq

---

StateCopy

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

One port’s committed state in a snapshot.

属性

名称	类型	说明
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.

实现的 Trait: 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.

属性

名称	类型	说明
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.

实现的 Trait: Clone, Debug

---

Built

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

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

属性

名称	类型	说明
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).

属性

名称	类型	说明
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).

属性

名称	类型	说明
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.

方法

函数	说明
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 &lt;operations&gt; in operations, zero allowed.

实现的 Trait: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

---

play::pad::PadButton

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

A pad’s button, by position.

变体

名称	说明
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.

实现的 Trait: 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.

变体

名称	说明
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.

实现的 Trait: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

---

play::PointerLook

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

What the pointer looks like over the window.

变体

名称	说明
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).

方法

函数	说明
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.

实现的 Trait: Clone, Debug, Eq, PartialEq, StructuralPartialEq

---

play::Frame

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

A frame’s result.

变体

名称	说明
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.

变体

名称	说明
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.

实现的 Trait: Clone, Debug, PartialEq, StructuralPartialEq

---

replay::Compare

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

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

变体

名称	说明
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.

实现的 Trait: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

---

Structure

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

What structure a restored snapshot runs in.

变体

名称	说明
Current	The scene as it stands.
Snapshot	The snapshot’s scene document, written back first.

实现的 Trait: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

---

Laws

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

What laws a restored snapshot runs under.

变体

名称	说明
Current	The running laws; state migrates where a layout changed.
Snapshot	The snapshot’s own Kernels, published back.

实现的 Trait: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

---

SessionError

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

Session-level failures.

变体

名称	说明
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.

实现的 Trait: Debug, Display, Error

---