Trait soroban_env_host::EnvBase

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

    // Required methods
    fn escalate_error_to_panic(&self, e: Self::Error) -> !;
    fn as_mut_any(&mut self) -> &mut (dyn Any + 'static);
    fn check_same_env(&self, other: &Self);
    fn deep_clone(&self) -> Self;
    fn bytes_copy_from_slice(
        &self,
        b: Object,
        b_pos: RawVal,
        mem: &[u8]
    ) -> Result<Object, Self::Error>;
    fn bytes_copy_to_slice(
        &self,
        b: Object,
        b_pos: RawVal,
        mem: &mut [u8]
    ) -> Result<(), Self::Error>;
    fn bytes_new_from_slice(&self, mem: &[u8]) -> Result<Object, Self::Error>;
    fn log_static_fmt_val(
        &self,
        fmt: &'static str,
        v: RawVal
    ) -> Result<(), Self::Error>;
    fn log_static_fmt_static_str(
        &self,
        fmt: &'static str,
        s: &'static str
    ) -> Result<(), Self::Error>;
    fn log_static_fmt_val_static_str(
        &self,
        fmt: &'static str,
        v: RawVal,
        s: &'static str
    ) -> Result<(), Self::Error>;
    fn log_static_fmt_general(
        &self,
        fmt: &'static str,
        vals: &[RawVal],
        strs: &[&'static str]
    ) -> Result<(), 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

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(Status) at the environment-interface level, and then either directly handle or escalate the contained Status code to the user as a Status or Result<> of some other type, depending on the API.

Required Methods

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. transforming or logging it). This should only ever be called by client-side / SDK local-testing code, never in the Host.

fn as_mut_any(&mut self) -> &mut (dyn Any + 'static)

Used for recovering the concrete type of the Host.

fn check_same_env(&self, other: &Self)

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

fn deep_clone(&self) -> Self

Used to clone an environment deeply, not just a handle to it.

fn bytes_copy_from_slice(
&self,
b: Object,
b_pos: RawVal,
mem: &[u8]
) -> Result<Object, Self::Error>

Copy a slice of bytes from the caller’s memory into an existing Bytes object the host, returning a new Bytes.

fn bytes_copy_to_slice(
&self,
b: Object,
b_pos: RawVal,
mem: &mut [u8]
) -> Result<(), Self::Error>

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

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

Form a new Bytes object in the host from a slice of memory in the caller.

fn log_static_fmt_val(
&self,
fmt: &'static str,
v: RawVal
) -> Result<(), Self::Error>

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and a single RawVal argument that will be inserted at the marker in the format string.

fn log_static_fmt_static_str(
&self,
fmt: &'static str,
s: &'static str
) -> Result<(), Self::Error>

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and a single string-slice argument that will be inserted at the marker in the format string.

fn log_static_fmt_val_static_str(
&self,
fmt: &'static str,
v: RawVal,
s: &'static str
) -> Result<(), Self::Error>

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and both a RawVal and a string-slice argument, that will each be inserted at markers in the format string.

fn log_static_fmt_general(
&self,
fmt: &'static str,
vals: &[RawVal],
strs: &[&'static str]
) -> Result<(), Self::Error>

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and both a slice of RawVals and a slice of string-slice argument, that will be sequentially inserted at markers in the format string.

Implementors

impl EnvBase for Host

type Error = HostError

impl EnvBase for UnimplementedEnv

type Error = Infallible