Struct gstd::Reservations

pub struct Reservations(/* private fields */);

Reservation manager.

The manager is used to control multiple gas reservations across executions. It can be used when you only care about reserved amounts and not concrete ReservationIds.

Examples

Create gas reservations inside init and use them inside handle.

use gstd::{msg, prelude::*, Reservations};

static mut RESERVATIONS: Reservations = Reservations::new();

#[no_mangle]
extern "C" fn init() {
    unsafe {
        RESERVATIONS
            .reserve(200_000, 50)
            .expect("failed to reserve gas");
        RESERVATIONS
            .reserve(100_000, 100)
            .expect("failed to reserve gas");
        RESERVATIONS
            .reserve(50_000, 30)
            .expect("failed to reserve gas");
    }
}

#[no_mangle]
extern "C" fn handle() {
    let reservation = unsafe { RESERVATIONS.try_take_reservation(100_000) };
    if let Some(reservation) = reservation {
        msg::send_bytes_from_reservation(
            reservation.id(),
            msg::source(),
            "send_bytes_from_reservation",
            0,
        )
        .expect("Failed to send message from reservation");
    } else {
        msg::send_bytes(msg::source(), "send_bytes", 0).expect("Failed to send message");
    }
}

See also

• ReservationId is used to reserve and unreserve gas for program execution later.
• Reservation stores some additional data along with ReservationId.

Implementations

impl Reservations

pub const fn new() -> Self

Create a new Reservations struct.

pub fn reserve(&mut self, amount: u64, duration: u32) -> Result<()>

Reserve the amount of gas for further usage.

duration is the block count within which the reservation must be used.

Underlying logics

Executes for O(logN)..O(N), where N is a number of stored reservations.

All the reservations are kept sorted by amount in ascending order(when amount is the same, they’re sorted by time when they expire) when inserted, so the closer inserted element to the beginning of the underlying Vec the closer execution time will be to O(N).

Also, when the underlying Vec will allocate new memory the attempt to clean expired reservations occurs to avoid memory allocations.

pub fn try_take_reservation(&mut self, amount: u64) -> Option<Reservation>

Find the appropriate reservation with reserved amount greater than or equal to amount.

If such a reservation is found, Reservation is returned.

Underlying logics

Executes for O(logN)..O(N), where N is amount of stored reservations. When there’s many expired reservations execution time is closer to O(N).

All the reservations are sorted by their amount and then by the time when they’ll expire (both are in ascending order) in underlying Vec, so when one’s trying to take reservation, reservation with the least possible amount is found and if it’s already expired, the search to the end of underlying Vec occurs. After that, all the expired reservations that were found in process of search are cleaned out.

See also

• ReservationId is used to reserve and unreserve gas amount for program execution later.
• Reservation stores some additional data along with ReservationId.

pub fn count_valid(&self) -> usize

Returns an amount of the stored reservations that aren’t expired at this time.

Executes for O(N) where N is amount of stored reservations.

pub fn count_all(&self) -> usize

Returns an amount of all the stored reservations (including expired).

Trait Implementations

impl Clone for Reservations

fn clone(&self) -> Reservations

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Reservations

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Decode for Reservations

fn decode<__CodecInputEdqy: Input>( __codec_input_edqy: &mut __CodecInputEdqy ) -> Result<Self, Error>

Attempt to deserialise the value from input.

fn decode_into<I>( input: &mut I, dst: &mut MaybeUninit<Self> ) -> Result<DecodeFinished, Error>

where I: Input,

Attempt to deserialize the value from input into a pre-allocated piece of memory.

fn skip<I>(input: &mut I) -> Result<(), Error>

where I: Input,

Attempt to skip the encoded value from input.

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type.

impl Default for Reservations

fn default() -> Reservations

Returns the “default value” for a type.

impl Encode for Reservations

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding.

fn encode_to<__CodecOutputEdqy: Output + ?Sized>( &self, __codec_dest_edqy: &mut __CodecOutputEdqy )

Convert self to a slice and append it to the destination.

fn encode(&self) -> Vec<u8>

Convert self to an owned vector.

fn using_encoded<R, F: FnOnce(&[u8]) -> R>(&self, f: F) -> R

Convert self to a slice and then invoke the given closure with it.

fn encoded_size(&self) -> usize

Calculates the encoded size.

impl Hash for Reservations

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl TypeInfo for Reservations

type Identity = Reservations

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.

impl EncodeLike for Reservations