Skip to main content

Inputs

Trait Inputs 

Source
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 binding_peek(
        &mut self,
        fn_name: &str,
        at: Option<&str>,
    ) -> Result<Option<FnBinding>, 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§

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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§

Source

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).

Source

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".

Implementors§