pub trait Inputs {
// Required methods
fn read(&mut self, fn_name: &str, args: &Args) -> Result<Scalar, EvalError>;
fn read_cell(
&mut self,
fn_name: &str,
args: &Args,
) -> Result<Input, EvalError>;
fn read_asof(
&mut self,
fn_name: &str,
args: &Args,
t: &str,
) -> Result<Input, EvalError>;
fn read_slice(
&mut self,
fn_name: &str,
pattern: &SlicePattern,
) -> Result<Vec<Member>, EvalError>;
fn read_versions(
&mut self,
fn_name: &str,
args: &Args,
from: &str,
to: &str,
) -> Result<Vec<Input>, EvalError>;
fn binding(
&mut self,
fn_name: &str,
at: Option<&str>,
) -> Result<Option<FnBinding>, EvalError>;
fn asof(&mut self) -> String;
// Provided methods
fn read_pinned(
&mut self,
fn_name: &str,
fn_hash: &str,
args: &Args,
) -> Result<Input, EvalError> { ... }
fn binding_peek(
&mut self,
fn_name: &str,
at: Option<&str>,
) -> Result<Option<FnBinding>, EvalError> { ... }
fn read_blob(
&mut self,
sha256: &str,
length: u64,
) -> Result<Vec<u8>, EvalError> { ... }
fn asof_compare(&mut self, t: &str) -> Result<Ordering, EvalError> { ... }
}Expand description
How a runtime reads the cells its function depends on, and the evaluation’s asof.
Every read checks that the function read is in the descriptor’s inputs
(EvalError::UndeclaredInput) and resolves its name (EvalError::NameUnresolved),
and is recorded: it becomes one of the computed receipt’s inputs entries, and the name’s
binding is relied on (its start is a candidate for the receipt’s asof, SPEC 8.2) as soon
as the read is attempted. The fuel each costs is SPEC 15.12’s.
Errors a runtime must propagate (with ?): EvalError::Suspended (an input not
evaluated yet: the engine evaluates it and calls the runtime again),
EvalError::InputNotCovered (an input with no value: neither has the cell, whatever the
runtime returns next), EvalError::BudgetExceeded and the engine’s failures. A
EvalError::Fault it may catch where its language allows (SPEC 15.12: otherwise
catches E_FORMULA_EMPTY and E_FORMULA_ABSENT).
Required Methods§
Sourcefn read(&mut self, fn_name: &str, args: &Args) -> Result<Scalar, EvalError>
fn read(&mut self, fn_name: &str, args: &Args) -> Result<Scalar, EvalError>
The value of the cell of function fn_name (fully qualified, <namespace>/<name>)
with arguments args, as of the evaluation’s asof: read_cell’s
value. Costs 1.
Sourcefn read_cell(&mut self, fn_name: &str, args: &Args) -> Result<Input, EvalError>
fn read_cell(&mut self, fn_name: &str, args: &Args) -> Result<Input, EvalError>
The cell of fn_name with args as of the evaluation’s asof: its value and the
receipt that answers (hash, tx, asof). A computed cell is evaluated by the engine;
its fault, if it has one, is returned (EvalError::Fault). Costs 1.
Sourcefn read_asof(
&mut self,
fn_name: &str,
args: &Args,
t: &str,
) -> Result<Input, EvalError>
fn read_asof( &mut self, fn_name: &str, args: &Args, t: &str, ) -> Result<Input, EvalError>
The cell of fn_name with args as of the transaction time t (SPEC 15.13,
asof(cell, T)): the name resolved as of t, the version answering as of t; an
ordinary single-cell input, and t a candidate for the receipt’s asof. t after the
evaluation’s asof is the fault E_FORMULA_FUTURE, before anything is read. Costs 1.
Sourcefn read_slice(
&mut self,
fn_name: &str,
pattern: &SlicePattern,
) -> Result<Vec<Member>, EvalError>
fn read_slice( &mut self, fn_name: &str, pattern: &SlicePattern, ) -> Result<Vec<Member>, EvalError>
The members of the slice of fn_name with pattern (every declared argument; at least
one open or ranged) as of the evaluation’s asof, in SPEC 15.13 key order: for a stored
function, its cells matching the pattern with a version answering then; for any other,
the cells of the declared extent (or, for a range over a date or integer number
argument without one, every day or integer in it) within the pattern, each evaluated
by the engine, and every one must have a value: else the read is the fault
E_FORMULA_ABSENT. One inputs entry slice:<slice id>:<members hash>, whose
manifest the engine stores. Costs 1 + members, charged once the members are obtained.
Sourcefn read_versions(
&mut self,
fn_name: &str,
args: &Args,
from: &str,
to: &str,
) -> Result<Vec<Input>, EvalError>
fn read_versions( &mut self, fn_name: &str, args: &Args, from: &str, to: &str, ) -> Result<Vec<Input>, EvalError>
The versions of the stored cell of fn_name with args whose tx is in [from, to],
as known as of the evaluation’s asof, ascending by tx (SPEC 15.13 versions): a
version slice, one inputs entry, to a candidate for the receipt’s asof. to after
the evaluation’s asof is E_FORMULA_FUTURE. Costs 1 + versions.
Sourcefn binding(
&mut self,
fn_name: &str,
at: Option<&str>,
) -> Result<Option<FnBinding>, EvalError>
fn binding( &mut self, fn_name: &str, at: Option<&str>, ) -> Result<Option<FnBinding>, EvalError>
The binding of fn_name as of the evaluation’s asof, or as of at: its function hash,
when it began and the descriptor; None when it has none then. Relied on as a read’s
name is. Free.
Sourcefn asof(&mut self) -> String
fn asof(&mut self) -> String
The evaluation’s asof (SPEC 15.12 asof()). Reading it makes the evaluation
asof-dependent (see Runtime::asof_dependent). Free.
Provided Methods§
Sourcefn read_pinned(
&mut self,
fn_name: &str,
fn_hash: &str,
args: &Args,
) -> Result<Input, EvalError>
fn read_pinned( &mut self, fn_name: &str, fn_hash: &str, args: &Args, ) -> Result<Input, EvalError>
The cell of the function fn_name at the function hash fn_hash, with args, as
of the evaluation’s asof: P/m@<fn_hash>(...) (SPEC 16.3 super). The cell is
evaluated with the descriptor stored under fn_hash and relies on no binding: the
name is not resolved, so no binding start is a candidate for the receipt’s asof and
a later rebinding of fn_name does not change the answer. Otherwise it is an
ordinary read (read_cell): the receipt becomes an inputs
entry, an evaluation is suspended and restarted, a fault is returned, and it costs 1.
fn_name must be declared in the descriptor’s inputs (EvalError::UndeclaredInput);
a fn_hash with no stored descriptor is a store failure (EvalError::Store,
NotFound). Since 0.4.2.
Provided: EvalError::Runtime (an Inputs with no pinned reads to offer; the
engine’s inputs override it). Being a provided method of a trait implemented by the
engine and by runtimes’ test doubles, it adds no obligation to an implementor.
Sourcefn binding_peek(
&mut self,
fn_name: &str,
at: Option<&str>,
) -> Result<Option<FnBinding>, EvalError>
fn binding_peek( &mut self, fn_name: &str, at: Option<&str>, ) -> Result<Option<FnBinding>, EvalError>
The binding of fn_name as of the evaluation’s asof, or as of at, looked up without
being relied on: no asof candidate, no dependency of the answer on the name. For a
runtime that needs to know what a name means (to check a body against it, say) before,
or without, reading it; a read of the name still relies on it. Free. Since 0.3.1.
Provided: binding, which relies on it (the engine’s inputs
override it).
Sourcefn read_blob(&mut self, sha256: &str, length: u64) -> Result<Vec<u8>, EvalError>
fn read_blob(&mut self, sha256: &str, length: u64) -> Result<Vec<u8>, EvalError>
The content of the blob whose SHA-256 is sha256 (64 lowercase hex digits) and whose
length is length bytes, as a blob value states them (<sha256>:<length>:<media type>, SPEC 3.7). Since 0.3.2, for text_of (SPEC 15.7).
The engine reads it from the store (Store::blob) and checks its length and SHA-256
against length and sha256. Content it cannot obtain, or that does not match, is
EvalError::BlobUnavailable: the evaluator’s failure, not a fault of the cell; the
request fails with it whatever the runtime does next. The content adds no inputs
entry (the blob is an input already, as an argument or an input’s value, and its
hash fixes the content), and it is free: the runtime charges what its language says
(SPEC 15.12: text_of 1 + bytes / 64, once the content is obtained), knowing the
length. The runtime checks the media type, before asking.
Provided: EvalError::BlobUnavailable (an Inputs with no content to offer).
Sourcefn asof_compare(&mut self, t: &str) -> Result<Ordering, EvalError>
fn asof_compare(&mut self, t: &str) -> Result<Ordering, EvalError>
How the instant t compares with the evaluation’s asof (t.cmp(asof)), without
making the evaluation asof-dependent when the answer cannot change at a later asof.
Free. Since 0.3.1.
What the engine records: when t is at or before the asof (Less or Equal), t is
a candidate for the receipt’s asof (as T of a transaction-time read is), so every
asof the receipt answers or is validated at is at or after t and the comparison gives
the same there; the receipt recomputes at its own asof. When t is after it
(Greater), the answer would change once the asof reaches t: the evaluation is then
asof-dependent, as by asof (and a runtime may report
E_FORMULA_FUTURE for it, even after an input without a value). A t that is not an
instant is EvalError::InvalidInput.
Provided: by asof, which always makes the evaluation asof-dependent
(the engine’s inputs override it).
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".