canic-core 0.26.1

Canic — a canister orchestration and management toolkit for the Internet Computer
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
127
128
129
130
131

use crate::workflow::runtime::timer::{TimerId, TimerWorkflow};
use std::{cell::RefCell, future::Future, rc::Rc, thread::LocalKey, time::Duration};

///
/// TimerHandle
/// Opaque handle for scheduled timers (no direct access to TimerId).
///

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TimerHandle(TimerId);

///
/// TimerSlot
/// Opaque timer slot handle for guarded scheduling.
///

pub type TimerSlot = LocalKey<RefCell<Option<TimerHandle>>>;

///
/// TimerApi
/// Lifecycle timer api façade for macro-expanded entrypoints.
///

pub struct TimerApi;

impl TimerApi {
    /// Public, stable surface for macro-expanded code in downstream crates.
    /// Performs no logic; delegates to internal TimerOps.
    pub fn set_lifecycle_timer(
        delay: Duration,
        label: impl Into<String>,
        task: impl Future<Output = ()> + 'static,
    ) -> TimerHandle {
        TimerHandle(TimerWorkflow::set(delay, label, task))
    }

    /// Schedule a one-shot timer only if the slot is empty.
    /// Returns true when a new timer was scheduled.
    pub fn set_guarded(
        slot: &'static TimerSlot,
        delay: Duration,
        label: impl Into<String>,
        task: impl Future<Output = ()> + 'static,
    ) -> bool {
        slot.with_borrow_mut(|entry| {
            if entry.is_some() {
                return false;
            }

            let id = TimerWorkflow::set(delay, label, task);
            *entry = Some(TimerHandle(id));
            true
        })
    }

    /// Schedule a repeating timer. Task produces a fresh Future on each tick.
    pub fn set_interval<F, Fut>(
        interval: Duration,
        label: impl Into<String>,
        task: F,
    ) -> TimerHandle
    where
        F: FnMut() -> Fut + 'static,
        Fut: Future<Output = ()> + 'static,
    {
        TimerHandle(TimerWorkflow::set_interval(interval, label, task))
    }

    /// Schedule a guarded init timer that installs a repeating interval timer.
    pub fn set_guarded_interval<FInit, InitFut, FTick, TickFut>(
        slot: &'static TimerSlot,
        init_delay: Duration,
        init_label: impl Into<String>,
        init_task: FInit,
        interval: Duration,
        interval_label: impl Into<String>,
        tick_task: FTick,
    ) -> bool
    where
        FInit: FnOnce() -> InitFut + 'static,
        InitFut: Future<Output = ()> + 'static,
        FTick: FnMut() -> TickFut + 'static,
        TickFut: Future<Output = ()> + 'static,
    {
        let init_label = init_label.into();
        let interval_label = interval_label.into();

        slot.with_borrow_mut(|entry| {
            if entry.is_some() {
                return false;
            }

            let init_id_cell = Rc::new(RefCell::new(None));
            let init_id_cell_task = Rc::clone(&init_id_cell);

            let init_id = TimerWorkflow::set(init_delay, init_label, async move {
                init_task().await;

                let init_id = init_id_cell_task.borrow();
                let Some(init_id) = init_id.as_ref() else {
                    return;
                };

                let still_armed = slot.with_borrow(|slot_val| slot_val.as_ref() == Some(init_id));
                if !still_armed {
                    return;
                }

                let interval_id = TimerWorkflow::set_interval(interval, interval_label, tick_task);
                let interval_handle = TimerHandle(interval_id);

                // Atomically replace the slot value and clear the previous timer id.
                // This prevents orphaned timers if callers clear around the handover.
                slot.with_borrow_mut(|slot_val| {
                    let old = slot_val.replace(interval_handle);
                    if let Some(old_id) = old
                        && old_id != interval_handle
                    {
                        TimerWorkflow::clear(old_id.0);
                    }
                });
            });

            let init_handle = TimerHandle(init_id);
            *init_id_cell.borrow_mut() = Some(init_handle);
            *entry = Some(init_handle);

            true
        })
    }
}