canic_core/macros/
start.rs

1//! # Canic Lifecycle Macros
2//!
3//! These macros define **compile-time lifecycle entry points** (`init` and `post_upgrade`)
4//! for Canic canisters. Lifecycle hooks must exist at the crate root with fixed names,
5//! so they cannot be registered dynamically — macros are therefore used to generate the
6//! boilerplate pre- and post-initialization logic automatically.
7//!
8//! Each macro sets up configuration, memory, timers, and TLS before calling user-defined
9//! async setup functions (`canic_setup`, `canic_install`, `canic_upgrade`), and then
10//! exposes the standard Canic endpoint suites.
11//!
12//! ## When to use which
13//!
14//! - [`macro@canic::start`] — for **non-root** canisters (standard services, workers, etc.).
15//! - [`macro@canic::start_root`] — for the **root orchestrator**, which performs
16//!   additional initialization for global registries and root-only extensions.
17
18/// Configure lifecycle hooks for **non-root Canic canisters**.
19///
20/// This macro wires up the `init` and `post_upgrade` entry points required by the IC,
21/// performing pre-initialization steps (config, memory, TLS, environment) before invoking
22/// user async functions:
23///
24/// ```ignore
25/// async fn canic_setup() { /* shared setup */ }
26/// async fn canic_install(args: Option<Vec<u8>>) { /* called after init */ }
27/// async fn canic_upgrade() { /* called after post_upgrade */ }
28/// ```
29///
30/// These functions are spawned asynchronously after bootstrap completes.
31/// The macro also exposes the standard non-root Canic endpoint suites.
32///
33/// This macro must be used instead of a normal function because the IC runtime requires
34/// `init` and `post_upgrade` to be declared at the top level.
35
36#[macro_export]
37macro_rules! start {
38    ($canister_type:expr) => {
39        #[::canic::cdk::init]
40        fn init(payload: ::canic::core::ops::CanisterInitPayload, args: Option<Vec<u8>>) {
41            ::canic::core::__canic_load_config!();
42
43            // ops
44            ::canic::core::ops::lifecycle::nonroot_init($canister_type, payload);
45
46            // timers — async body, no spawn()
47            let _ =
48                ::canic::cdk::timers::set_timer(::std::time::Duration::from_secs(0), async move {
49                    canic_setup().await;
50                    canic_install(args).await;
51                });
52        }
53
54        #[::canic::cdk::post_upgrade]
55        fn post_upgrade() {
56            ::canic::core::__canic_load_config!();
57
58            // ops
59            ::canic::core::ops::lifecycle::nonroot_post_upgrade($canister_type);
60
61            // timers — async body, no spawn()
62            let _ =
63                ::canic::cdk::timers::set_timer(::std::time::Duration::from_secs(0), async move {
64                    canic_setup().await;
65                    canic_upgrade().await;
66                });
67        }
68
69        ::canic::core::canic_endpoints!();
70        ::canic::core::canic_endpoints_nonroot!();
71    };
72}
73
74///
75/// Configure lifecycle hooks for the **root Canic orchestrator canister**.
76///
77/// This macro behaves like [`macro@canic::start`], but includes additional
78/// root-only initialization for:
79///
80/// - the global subnet registry
81/// - root-only memory extensions and cycle tracking
82/// - the root endpoint suite
83///
84/// It generates the `init` and `post_upgrade` hooks required by the IC, loads embedded
85/// configuration, imports the root `WASMS` bundle, and runs pre- and post-upgrade logic
86/// in [`ops::lifecycle`].
87///
88/// Use this for the root orchestrator canister only. Other canisters should use
89/// [`macro@canic::start`].
90
91#[macro_export]
92macro_rules! start_root {
93    () => {
94        #[::canic::cdk::init]
95        fn init(identity: ::canic::core::model::memory::topology::SubnetIdentity) {
96            ::canic::core::__canic_load_config!();
97
98            // ops
99            ::canic::core::ops::lifecycle::root_init(identity);
100
101            // import wasms
102            ::canic::core::ops::wasm::WasmOps::import_static(WASMS);
103
104            // timers
105            let _ =
106                ::canic::cdk::timers::set_timer(std::time::Duration::from_secs(0), async move {
107                    ::canic::core::ops::root::root_set_subnet_id().await;
108                    ::canic::core::ops::root::root_create_canisters()
109                        .await
110                        .unwrap();
111
112                    canic_setup().await;
113                    canic_install().await;
114                });
115        }
116
117        #[::canic::cdk::post_upgrade]
118        fn post_upgrade() {
119            ::canic::core::__canic_load_config!();
120            ::canic::core::ops::wasm::WasmOps::import_static(WASMS);
121
122            // ops
123            ::canic::core::ops::lifecycle::root_post_upgrade();
124
125            // timers
126            let _ =
127                ::canic::cdk::timers::set_timer(::std::time::Duration::from_secs(0), async move {
128                    canic_setup().await;
129                    canic_upgrade().await;
130                });
131        }
132
133        ::canic::core::canic_endpoints!();
134        ::canic::core::canic_endpoints_root!();
135    };
136}
137
138//
139// Private helpers
140//
141
142///
143/// Load the embedded configuration during init and upgrade hooks.
144///
145/// This macro exists solely to embed and load the TOML configuration file
146/// at compile time (`CANIC_CONFIG_PATH`). It is used internally by
147/// [`macro@canic::start`] and [`macro@canic::start_root`].
148
149#[doc(hidden)]
150#[macro_export]
151macro_rules! __canic_load_config {
152    () => {
153        #[cfg(canic)]
154        {
155            let config_str = include_str!(env!("CANIC_CONFIG_PATH"));
156            $crate::config::Config::init_from_toml(config_str).unwrap();
157        }
158    };
159}
canic_core/macros/start.rs

canic_core/macros/
start.rs
