gstd 2.0.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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

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

// TODO: describe denied syscalls in entrypoint (#3580)
//! Critical hook that guarantees code section execution.
//!
//! __Hook is set on per-message basis.__
//!
//! Code is executed in `handle_signal` entry point in case of failure
//! only across [`exec::wait()`] calls because hook has to be saved.
//!
//! ```rust,no_run
//! use gstd::{critical, msg};
//!
//! # async fn _dummy() {
//! // get source outside of critical hook
//! // because `gr_source` syscall is forbidden inside `handle_signal` entry point
//! let source = msg::source();
//!
//! critical::set_hook(move || {
//!     msg::send(source, "sends failed", 0).expect("Failed to send emergency message");
//! });
//!
//! let msg = msg::send_for_reply(source, "send_for_reply", 0, 0)
//!     .expect("Failed to send message")
//!     // await on `MessageFuture` which calls `exec::wait()` inside
//!     // so program state will be saved and thus hook will too
//!     .await
//!     .expect("Received error reply");
//!
//! // if some code fails (panic, out of gas, etc) after `exec::wait()` and friends
//! // then saved hook will be executed in `handle_signal`
//!
//! // your code
//! // ...
//!
//! # }
//! ```
//!
//! [`exec::wait()`]: crate::exec::wait

use crate::{MessageId, msg};
use alloc::boxed::Box;
use hashbrown::HashMap;

type HooksMap = HashMap<MessageId, Box<dyn FnMut()>>;

static mut HOOKS: Option<HooksMap> = None;

fn hooks() -> &'static mut HooksMap {
    unsafe { crate::static_mut!(HOOKS).get_or_insert_with(HashMap::new) }
}

/// Sets a critical hook.
///
/// # PANICS
/// If called in the `handle_reply` or `handle_signal` entrypoints.
///
/// # SAFETY
/// Ensure that sufficient `gstd::Config::SYSTEM_RESERVE` is set in your
/// program, as this gas is locked during each async call to provide resources
/// for hook execution in case it is triggered.
pub fn set_hook<F: FnMut() + 'static>(f: F) {
    if msg::reply_code().is_ok() {
        panic!("`gstd::critical::set_hook()` must not be called in `handle_reply` entrypoint")
    }

    if msg::signal_code().is_ok() {
        panic!("`gstd::critical::set_hook()` must not be called in `handle_signal` entrypoint")
    }

    hooks().insert(msg::id(), Box::new(f));
}

/// Removes current hook and returns it.
///
/// __Don't use it at all if you use
/// [`#[gstd::async_init]`](crate::async_init) or
/// [`#[gstd::async_main]`](crate::async_main).__
///
/// Must be called at the end of `init` or `handle`
/// to not blow up map because hook is set on per-message basis:
///
/// ```rust,no_run
/// use gstd::critical;
///
/// #[unsafe(no_mangle)]
/// extern "C" fn handle() {
///     critical::set_hook(|| {
///         // some code...
///     });
///
///     // handle code...
///
///     let _ = critical::take_hook();
/// }
/// ```
pub fn take_hook() -> Option<Box<dyn FnMut()>> {
    hooks().remove(&msg::id())
}

/// Removes current hook and executes it.
///
/// __Don't use it at all if you use
/// [`#[gstd::async_init]`](crate::async_init) or
/// [`#[gstd::async_main]`](crate::async_main).__
///
/// Must be called inside `handle_signal`:
///
/// ```rust,no_run
/// use gstd::critical;
///
/// #[unsafe(no_mangle)]
/// extern "C" fn handle_signal() {
///     critical::take_and_execute();
/// }
/// ```
pub fn take_and_execute() {
    let msg_id = msg::signal_from().expect(
        "`gstd::critical::execute_hook_once()` must be called only in `handle_signal` entrypoint",
    );

    if let Some(mut f) = hooks().remove(&msg_id) {
        f();
    }
}