gstd 1.10.0

Gear programs standard library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

// This file is part of Gear.

// Copyright (C) 2021-2025 Gear Technologies Inc.
// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0

// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.

// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.

// You should have received a copy of the GNU General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.

use crate::ReservationId;
use gcore::errors::Result;

mod private {
    use crate::ReservationId;

    pub trait Sealed {}

    impl Sealed for ReservationId {}
}

/// Reservation identifier extension.
///
/// The identifier is used to reserve and unreserve gas amount for program
/// execution later.
///
/// # Examples
///
/// ```rust,ignore
/// use gstd::{prelude::*, ReservationId};
///
/// static mut RESERVED: Option<ReservationId> = None;
///
/// #[unsafe(no_mangle)]
/// extern "C" fn init() {
///     let reservation_id = ReservationId::reserve(50_000_000, 7).expect("Unable to reserve");
///     unsafe { RESERVED = Some(reservation_id) };
/// }
///
/// #[unsafe(no_mangle)]
/// extern "C" fn handle() {
///     let reservation_id = unsafe { RESERVED.take().expect("Empty `RESERVED`") };
///     reservation_id.unreserve().expect("Unable to unreserve");
/// }
/// ```
pub trait ReservationIdExt: private::Sealed + Sized {
    /// Reserve the `amount` of gas for further usage.
    ///
    /// `duration` is the block count within which the reserve must be used.
    ///
    /// This function returns [`ReservationId`], which one can use for gas
    /// unreserving.
    ///
    /// # Examples
    ///
    /// Reserve 50 million of gas for one block, send a reply, then unreserve
    /// gas back:
    ///
    /// ```
    /// use gstd::{ReservationId, msg, prelude::*};
    ///
    /// #[unsafe(no_mangle)]
    /// extern "C" fn handle() {
    ///     let reservation_id = ReservationId::reserve(50_000_000, 1).expect("Unable to reserve");
    ///     msg::reply_bytes_from_reservation(reservation_id.clone(), b"PONG", 0)
    ///         .expect("Unable to reply");
    ///     let reservation_left = reservation_id.unreserve().expect("Unable to unreserve");
    /// }
    /// ```
    fn reserve(amount: u64, duration: u32) -> Result<Self>;

    /// Unreserve unused gas from the reservation.
    ///
    /// If successful, it returns the reserved amount of gas.
    fn unreserve(self) -> Result<u64>;
}

impl ReservationIdExt for ReservationId {
    fn reserve(amount: u64, duration: u32) -> Result<Self> {
        gcore::exec::reserve_gas(amount, duration)
    }

    fn unreserve(self) -> Result<u64> {
        gcore::exec::unreserve_gas(self)
    }
}