Trait soroban_env_host::EnvBase
source · pub trait EnvBase: Sized + Clone {
type Error: Debug + Into<Error> + From<Error>;
Show 18 methods
// 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: 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: &str
) -> Result<StringObject, Self::Error>;
fn symbol_new_from_slice(
&self,
slice: &str
) -> 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>;
// Provided method
fn augment_err_result<T>(
&self,
x: Result<T, Self::Error>
) -> Result<T, Self::Error> { ... }
}
Expand description
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§
sourcetype Error: Debug + Into<Error> + From<Error>
type Error: Debug + Into<Error> + From<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§
sourcefn escalate_error_to_panic(&self, e: Self::Error) -> !
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
.
sourcefn as_mut_any(&mut self) -> &mut (dyn Any + 'static)
fn as_mut_any(&mut self) -> &mut (dyn Any + 'static)
Used for recovering the concrete type of the Host.
sourcefn check_same_env(&self, other: &Self)
fn check_same_env(&self, other: &Self)
Used to check two environments are the same, trapping if not.
sourcefn deep_clone(&self) -> Self
fn deep_clone(&self) -> Self
Used to clone an environment deeply, not just a handle to it.
sourcefn bytes_copy_from_slice(
&self,
b: BytesObject,
b_pos: U32Val,
slice: &[u8]
) -> Result<BytesObject, Self::Error>
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
.
sourcefn bytes_copy_to_slice(
&self,
b: BytesObject,
b_pos: U32Val,
slice: &mut [u8]
) -> Result<(), Self::Error>
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.
sourcefn string_copy_to_slice(
&self,
b: StringObject,
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>
Copy a slice of bytes from a String
object in the host into a slice in
the caller’s memory.
sourcefn symbol_copy_to_slice(
&self,
b: SymbolObject,
b_pos: U32Val,
mem: &mut [u8]
) -> Result<(), Self::Error>
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.
sourcefn bytes_new_from_slice(&self, slice: &[u8]) -> Result<BytesObject, Self::Error>
fn bytes_new_from_slice(&self, slice: &[u8]) -> Result<BytesObject, Self::Error>
Form a new Bytes
host object from a slice of client memory.
sourcefn string_new_from_slice(
&self,
slice: &str
) -> Result<StringObject, Self::Error>
fn string_new_from_slice( &self, slice: &str ) -> Result<StringObject, Self::Error>
Form a new String
host object from a slice of client memory.
sourcefn symbol_new_from_slice(
&self,
slice: &str
) -> Result<SymbolObject, Self::Error>
fn symbol_new_from_slice( &self, slice: &str ) -> Result<SymbolObject, Self::Error>
Form a new Symbol
host object from a slice of client memory.
sourcefn map_new_from_slices(
&self,
keys: &[&str],
vals: &[Val]
) -> Result<MapObject, Self::Error>
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.
sourcefn map_unpack_to_slice(
&self,
map: MapObject,
keys: &[&str],
vals: &mut [Val]
) -> Result<Void, Self::Error>
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
Val
s. Keys must be in sorted order and must match the key set of
the unpacked object exactly.
sourcefn vec_new_from_slice(&self, vals: &[Val]) -> Result<VecObject, Self::Error>
fn vec_new_from_slice(&self, vals: &[Val]) -> Result<VecObject, Self::Error>
Form a new Vec
host object from a slice of values.
sourcefn vec_unpack_to_slice(
&self,
vec: VecObject,
vals: &mut [Val]
) -> Result<Void, Self::Error>
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.
Provided Methods§
sourcefn augment_err_result<T>(
&self,
x: Result<T, Self::Error>
) -> Result<T, Self::Error>
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.