canic 0.109.11

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

//! Facade macros for downstream canister crates.
mod build;
mod endpoints;
mod start;

// -----------------------------------------------------------------------------
// Application scope macro
// -----------------------------------------------------------------------------

/// Construct one statically validated canonical application scope.
///
/// ```
/// const READ: canic::access::auth::ApplicationScopeRef<'static> =
///     canic::application_scope!("my_app:read");
/// assert_eq!(READ.as_str(), "my_app:read");
/// ```
///
/// ```compile_fail
/// const INVALID: canic::access::auth::ApplicationScopeRef<'static> =
///     canic::application_scope!("my.app:read");
/// ```
#[macro_export]
macro_rules! application_scope {
    ($scope:literal) => {{ const { $crate::access::auth::ApplicationScopeRef::from_static($scope) } }};
}

// -----------------------------------------------------------------------------
// Log macro
// -----------------------------------------------------------------------------

/// Log a runtime entry using Canic's structured logger.
#[macro_export]
macro_rules! log {
    ($($tt:tt)*) => {{
        $crate::__internal::core::log!($($tt)*);
    }};
}

// -----------------------------------------------------------------------------
// Perf macro
// -----------------------------------------------------------------------------

/// Record and log elapsed instruction counts since the last `perf!` invocation
/// in this thread.
///
/// - Uses a thread-local `PERF_LAST` snapshot.
/// - Computes `delta = now - last`.
/// - Records a structured checkpoint row in the shared perf table.
/// - Prints a human-readable line for debugging.
///
/// Intended usage:
/// - Long-running maintenance tasks where you want *checkpoints* in a single call.
///
/// Note: `perf!` is independent of endpoint perf scopes and does not touch the
/// endpoint stack used by dispatch. It records checkpoint rows keyed by
/// `module_path!()` plus the formatted label.
///
/// Notes:
/// - On non-wasm targets, `perf_counter()` returns 0, so this becomes a no-op-ish
///   counter (still records 0 deltas); this keeps unit tests compiling cleanly.
#[macro_export]
macro_rules! perf {
    ($($label:tt)*) => {{
        $crate::__internal::core::perf::PERF_LAST.with(|last| {
            // Use the wrapper so non-wasm builds compile.
            let now = $crate::__internal::core::perf::perf_counter();
            let then = *last.borrow();
            let delta = now.saturating_sub(then);

            // Update last checkpoint.
            *last.borrow_mut() = now;

            // Format label + pretty-print counters.
            let label = format!($($label)*);
            let delta_fmt = $crate::__internal::instructions::format_instructions(delta);
            let now_fmt = $crate::__internal::instructions::format_instructions(now);

            $crate::__internal::core::perf::record_checkpoint(module_path!(), &label, delta);

            $crate::__internal::core::log!(
                Info,
                Topic::Perf,
                "{}: '{}' used {}i since last (total: {}i)",
                module_path!(),
                label,
                delta_fmt,
                now_fmt
            );
        });
    }};
}