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 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§

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

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

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§