Struct soroban_env_host::storage::Storage

pub struct Storage {
    pub footprint: Footprint,
    pub mode: FootprintMode,
    pub map: StorageMap,
}

A special-purpose map from LedgerKeys to LedgerEntrys. Represents a transactional batch of contract IO from and to durable storage, while partitioning that IO between concurrently executing groups of contracts through the use of IO Footprints.

Specifically: access to each LedgerKey is mediated by the Footprint, which may be in either FootprintMode::Recording or FootprintMode::Enforcing mode.

FootprintMode::Recording mode is used to calculate Footprints during “preflight” execution of a contract. Once calculated, a recorded Footprint can be provided to “real” execution, which always runs in FootprintMode::Enforcing mode and enforces partitioned access.

Fields

footprint: Footprint

mode: FootprintMode

map: StorageMap

Implementations

impl Storage

pub fn with_enforcing_footprint_and_map( footprint: Footprint, map: StorageMap ) -> Self

Constructs a new Storage in FootprintMode::Enforcing using a given Footprint and a storage map populated with all the keys listed in the Footprint.

pub fn with_recording_footprint(src: Rc<dyn SnapshotSource>) -> Self

Constructs a new Storage in FootprintMode::Recording using a given SnapshotSource.

pub fn get( &mut self, key: &Rc<LedgerKey>, budget: &Budget ) -> Result<Rc<LedgerEntry>, HostError>

Attempts to retrieve the LedgerEntry associated with a given LedgerKey in the Storage, returning an error if the key is not found.

In FootprintMode::Recording mode, records the read LedgerKey in the Footprint as AccessType::ReadOnly (unless already recorded as AccessType::ReadWrite) and reads through to the underlying SnapshotSource, if the LedgerKey has not yet been loaded.

In FootprintMode::Enforcing mode, succeeds only if the read LedgerKey has been declared in the Footprint.

pub fn put( &mut self, key: &Rc<LedgerKey>, val: &Rc<LedgerEntry>, expiration_ledger: Option<u32>, budget: &Budget ) -> Result<(), HostError>

Attempts to write to the LedgerEntry associated with a given LedgerKey in the Storage.

In FootprintMode::Recording mode, records the written LedgerKey in the Footprint as AccessType::ReadWrite.

In FootprintMode::Enforcing mode, succeeds only if the written LedgerKey has been declared in the Footprint as AccessType::ReadWrite.

pub fn del( &mut self, key: &Rc<LedgerKey>, budget: &Budget ) -> Result<(), HostError>

Attempts to delete the LedgerEntry associated with a given LedgerKey in the Storage.

In FootprintMode::Recording mode, records the deleted LedgerKey in the Footprint as AccessType::ReadWrite.

In FootprintMode::Enforcing mode, succeeds only if the deleted LedgerKey has been declared in the Footprint as AccessType::ReadWrite.

pub fn has( &mut self, key: &Rc<LedgerKey>, budget: &Budget ) -> Result<bool, HostError>

Attempts to determine the presence of a LedgerEntry associated with a given LedgerKey in the Storage, returning Ok(true) if an entry with the key exists and Ok(false) if it does not.

In FootprintMode::Recording mode, records the access and reads-through to the underlying SnapshotSource.

In FootprintMode::Enforcing mode, succeeds only if the access has been declared in the Footprint.

pub fn bump( &mut self, host: &Host, key: Rc<LedgerKey>, low_expiration_watermark: u32, high_expiration_watermark: u32 ) -> Result<(), HostError>

Bumps key to live for at least bump_by_ledgers from now (not counting the current ledger).

This operation is only defined within a host as it relies on ledger state.

This operation does not modify any ledger entries, but does change the internal storage

Trait Implementations

impl Clone for Storage

fn clone(&self) -> Storage

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Storage

fn default() -> Storage

Returns the “default value” for a type.