Trait EnvBase

pub trait EnvBase: Sized + Clone {
    type Error: Debug + Into<Error>;

    // Required methods
    fn error_from_error_val(&self, e: Error) -> Self::Error;
    fn escalate_error_to_panic(&self, e: Self::Error) -> !;
    fn check_same_env(&self, other: &Self) -> Result<(), Self::Error>;
    fn bytes_copy_from_slice(
        &self,
        b: BytesObject,
        b_pos: U32Val,
        slice: &[u8],
    ) -> Result<BytesObject, Self::Error>;
    fn bytes_copy_to_slice(
        &self,
        b: BytesObject,
        b_pos: U32Val,
        slice: &mut [u8],
    ) -> Result<(), Self::Error>;
    fn string_copy_to_slice(
        &self,
        b: StringObject,
        b_pos: U32Val,
        slice: &mut [u8],
    ) -> Result<(), Self::Error>;
    fn symbol_copy_to_slice(
        &self,
        b: SymbolObject,
        b_pos: U32Val,
        mem: &mut [u8],
    ) -> Result<(), Self::Error>;
    fn bytes_new_from_slice(
        &self,
        slice: &[u8],
    ) -> Result<BytesObject, Self::Error>;
    fn string_new_from_slice(
        &self,
        slice: &[u8],
    ) -> Result<StringObject, Self::Error>;
    fn symbol_new_from_slice(
        &self,
        slice: &[u8],
    ) -> Result<SymbolObject, Self::Error>;
    fn map_new_from_slices(
        &self,
        keys: &[&str],
        vals: &[Val],
    ) -> Result<MapObject, Self::Error>;
    fn map_unpack_to_slice(
        &self,
        map: MapObject,
        keys: &[&str],
        vals: &mut [Val],
    ) -> Result<Void, Self::Error>;
    fn vec_new_from_slice(&self, vals: &[Val]) -> Result<VecObject, Self::Error>;
    fn vec_unpack_to_slice(
        &self,
        vec: VecObject,
        vals: &mut [Val],
    ) -> Result<Void, Self::Error>;
    fn symbol_index_in_strs(
        &self,
        key: Symbol,
        strs: &[&str],
    ) -> Result<U32Val, Self::Error>;
    fn log_from_slice(
        &self,
        msg: &str,
        vals: &[Val],
    ) -> Result<Void, Self::Error>;
    fn check_protocol_version_lower_bound(
        &self,
        lower_bound: u32,
    ) -> Result<(), Self::Error>;
    fn check_protocol_version_upper_bound(
        &self,
        upper_bound: u32,
    ) -> Result<(), Self::Error>;

    // Provided methods
    fn check_val_integrity(&self, val: Val) -> Result<(), Self::Error> { ... }
    fn check_obj_integrity(&self, _obj: Object) -> Result<(), Self::Error> { ... }
    fn env_call_hook(
        &self,
        _fname: &'static str,
        _args: &[String],
    ) -> Result<(), Self::Error> { ... }
    fn env_ret_hook(
        &self,
        _fname: &'static str,
        _res: &Result<String, &Self::Error>,
    ) -> Result<(), Self::Error> { ... }
    fn tracing_enabled(&self) -> bool { ... }
    fn trace_env_call(
        &self,
        _fname: &'static str,
        _args: &[&dyn Debug],
    ) -> Result<(), Self::Error> { ... }
    fn trace_env_ret(
        &self,
        _fname: &'static str,
        _res: &Result<&dyn Debug, &Self::Error>,
    ) -> Result<(), Self::Error> { ... }
    fn augment_err_result<T>(
        &self,
        x: Result<T, Self::Error>,
    ) -> Result<T, Self::Error> { ... }
}

Base trait extended by the Env trait, providing various special-case functions that do not simply call across cross the guest/host interface.

Required Associated Types

type Error: Debug + Into<Error>

The type of error returned from the environment when the environment itself fails “unrecoverably”, or at least in a way that the user is not expected to be able to recover from, such as an internal logic error, exceeding the execution budget, or being passed malformed input in a way that the user-facing API does not anticipate or allow for. This type is returned from all environment-interface methods, and will only ever take on two possible concrete types: either Infallible (in the Guest) or HostError (in the Host).

The Guest can treat all such errors as impossible-to-observe since they will result in the Host trapping the Guest before returning an Error to it. Such errors still remain present in the Env API so that we can use the same API in both scenarios, rather than having to have separate “fallible” or “infallible” environments and separate conversion routines for each (as was attempted in earlier iterations).

This type is not the same as an error intended to make it to the user-facing API: user-facing errors should return Ok(Error) at the environment-interface level, and then either directly handle or escalate the contained Error code to the user as a Error or Result<> of some other type, depending on the API.

Required Methods

fn error_from_error_val(&self, e: Error) -> Self::Error

Convert a crate::Error into EnvBase::Error. This is similar to adding + From<crate::Error> to the associated type bound for EnvBase::Error but it allows us to restrict that conversion in downstream crates, which is desirable to keep “conversions that panic” (as the guest definition of EnvBase::Error does) out of the common crate and avoid accidentally triggering them in the host. It also gives the Env an opportunity to log or enrich the error with context (both of which happen in Host).

fn escalate_error_to_panic(&self, e: Self::Error) -> !

Reject an error from the environment, turning it into a panic but on terms that the environment controls (eg. enriching or logging it). This should only ever be called by client-side / SDK local-testing code, never in the Host.

fn check_same_env(&self, other: &Self) -> Result<(), Self::Error>

Used to check two environments are the same, returning Error if not.

fn bytes_copy_from_slice( &self, b: BytesObject, b_pos: U32Val, slice: &[u8], ) -> Result<BytesObject, Self::Error>

Clone an existing Bytes object in the host, replacing the portion of its memory with bytes supplied by slice, returning the new object. The replaced portion of the original object’s memory begins at b_pos and extends for the same length as the new slice.

fn bytes_copy_to_slice( &self, b: BytesObject, b_pos: U32Val, slice: &mut [u8], ) -> Result<(), Self::Error>

Copy a slice of bytes from a Bytes object in the host into a slice in the caller’s memory.

fn string_copy_to_slice( &self, b: StringObject, b_pos: U32Val, slice: &mut [u8], ) -> Result<(), Self::Error>

Copy a slice of bytes from a String object in the host into a slice in the caller’s memory.

fn symbol_copy_to_slice( &self, b: SymbolObject, b_pos: U32Val, mem: &mut [u8], ) -> Result<(), Self::Error>

Copy a slice of bytes from a Symbol object in the host into the caller’s memory.

fn bytes_new_from_slice(&self, slice: &[u8]) -> Result<BytesObject, Self::Error>

Form a new Bytes host object from a slice of client memory.

fn string_new_from_slice( &self, slice: &[u8], ) -> Result<StringObject, Self::Error>

Form a new String host object from a slice of client memory.

fn symbol_new_from_slice( &self, slice: &[u8], ) -> Result<SymbolObject, Self::Error>

Form a new Symbol host object from a slice of client memory.

fn map_new_from_slices( &self, keys: &[&str], vals: &[Val], ) -> Result<MapObject, Self::Error>

Form a new Map host object from a slice of symbol-names and a slice of values. Keys must be in sorted order.

fn map_unpack_to_slice( &self, map: MapObject, keys: &[&str], vals: &mut [Val], ) -> Result<Void, Self::Error>

Unpack a Map host object with a specified set of keys to a slice of Vals. Keys must be in sorted order and must match the key set of the unpacked object exactly.

fn vec_new_from_slice(&self, vals: &[Val]) -> Result<VecObject, Self::Error>

Form a new Vec host object from a slice of values.

fn vec_unpack_to_slice( &self, vec: VecObject, vals: &mut [Val], ) -> Result<Void, Self::Error>

Form a new Vec host object from a slice of values. The values slice must be the same length as the host object.

fn symbol_index_in_strs( &self, key: Symbol, strs: &[&str], ) -> Result<U32Val, Self::Error>

Return the index of a Symbol in an array of &strs, or error if not found.

fn log_from_slice(&self, msg: &str, vals: &[Val]) -> Result<Void, Self::Error>

Log a string and set of values as a diagnostic event, if diagnostic events are enabled. When running on host, logs directly; when running on guest, redirects through log_from_linear_memory.

fn check_protocol_version_lower_bound( &self, lower_bound: u32, ) -> Result<(), Self::Error>

Check the current ledger protocol version against a provided lower bound, error if protocol version is out-of-bound.

fn check_protocol_version_upper_bound( &self, upper_bound: u32, ) -> Result<(), Self::Error>

Check the current ledger protocol version against a provided upper bound, error if protocol version is out-of-bound.

Provided Methods

fn check_val_integrity(&self, val: Val) -> Result<(), Self::Error>

Check that a Val is good according to the current Env. This is a superset of calling Val::good as it also checks that if the Val is an Object, that the Object is good according to Self::check_obj_integrity.

fn check_obj_integrity(&self, _obj: Object) -> Result<(), Self::Error>

Check that an Object handle is good according to the current Env. For general Val-validity checking one should use Val::good().

fn env_call_hook( &self, _fname: &'static str, _args: &[String], ) -> Result<(), Self::Error>

👎Deprecated: replaced by trace_env_call

fn env_ret_hook( &self, _fname: &'static str, _res: &Result<String, &Self::Error>, ) -> Result<(), Self::Error>

👎Deprecated: replaced by trace_env_ret

fn tracing_enabled(&self) -> bool

Return true if the environment wants to receive trace calls and and returns using Self::trace_env_call and Self::trace_env_ret.

fn trace_env_call( &self, _fname: &'static str, _args: &[&dyn Debug], ) -> Result<(), Self::Error>

A general interface for tracing all env-method calls, intended to be called from macros that do dispatch on all such methods.

fn trace_env_ret( &self, _fname: &'static str, _res: &Result<&dyn Debug, &Self::Error>, ) -> Result<(), Self::Error>

A general interface for tracing all env-method returns, intended to be called from macros that do dispatch on all such methods.

fn augment_err_result<T>( &self, x: Result<T, Self::Error>, ) -> Result<T, Self::Error>

If x is Err(...), ensure as much debug information as possible is attached to that error; in any case return “essentially the same” x – either Ok(...) or Err(...) – just with extra error context.

This is called on a best-effort basis while propagating errors in the host, to attach context “as soon as possible”, and is necessary because some errors are generated in contexts that do not have access to a Host, and so cannot attach error context at the site of error generation.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl EnvBase for Host

type Error = HostError