nichlink_run_method/macros/
trace.rs

1//! Trace recording macros.
2//! 追踪记录宏。
3
4/// Record one logical function invocation with its source location.
5/// 用一条宏调用记录一次逻辑函数调用，并保留源码位置。
6///
7/// The closure is deliberately the only required wrapper. It keeps the
8/// tracing boundary explicit, works on stable Rust, and does not introduce a
9/// trait object or a global callback into the hot path.
10/// 闭包是唯一必须写出的边界，兼容 stable Rust；不会引入 trait object，
11/// 也不会在热路径上增加全局回调。
12#[macro_export]
13macro_rules! trace_call {
14    ($trace:expr, $node:expr, $function:literal, $operation:expr) => {{ $trace.with($node, $function, $operation) }};
15}
16
17/// Record a fallible invocation according to the trace policy.
18/// 按追踪策略记录一个可失败的函数调用。
19///
20/// In `errors-only` mode, successful scopes are discarded and `Err`/panic
21/// scopes remain available for diagnostics. Other modes keep their normal
22/// behavior.
23/// 在 `errors-only` 模式下成功作用域会回滚，`Err` 或 panic 作用域会保留供诊断；
24/// 其它模式保持正常收集行为。
25#[macro_export]
26macro_rules! trace_call_result {
27    ($trace:expr, $operation:expr) => {{ $trace.with_result($operation) }};
28}
29
30/// Capture a function input or local value at the macro call site.
31/// 在宏调用位置记录函数输入或局部值。
32#[macro_export]
33macro_rules! trace_value {
34    ($trace:expr, $name:literal, $type_name:literal, $value:expr, $kind:expr) => {{ $trace.local($name, $type_name, $value, $kind) }};
35}
36
37/// Capture a transformed value and connect it to its producer.
38/// 记录转换后的值，并把它连接到生产者。
39#[macro_export]
40macro_rules! trace_transform {
41    ($trace:expr, $input:expr, $name:literal, $type_name:literal, $value:expr) => {{ $trace.transform($input, $name, $type_name, $value) }};
42}
43
44/// Capture a value consumed by another function parameter.
45/// 记录值被另一个函数参数消费的位置。
46#[macro_export]
47macro_rules! trace_consume {
48    ($trace:expr, $input:expr, $function:literal, $parameter:literal) => {{ $trace.consume($input, $function, $parameter) }};
49}
50
51/// Capture a function return value and connect it to its input.
52/// 记录函数返回值，并把它连接到输入值。
53#[macro_export]
54macro_rules! trace_return {
55    ($trace:expr, $input:expr, $name:literal, $type_name:literal, $value:expr) => {{ $trace.return_value($input, $name, $type_name, $value) }};
56}
nichlink_run_method/macros/trace.rs

nichlink_run_method/macros/
trace.rs
