Skip to main content

xirang_kernel/registry_core/declaration/
call_evidence.rs

1//! Observed call edges, evidence, and the trace mode that records them.
2//! 已观测的调用边、证据,以及记录它们的追踪模式。
3
4use super::*;
5
6/// One observed call site: which node and function were active in which trace frame, and
7/// where the call was written. A `CallEdge` is the pair of sites that make up the edge.
8/// 一处被观测到的调用点:哪个节点、哪个函数在哪个追踪帧里处于活动状态,以及这次调用写在哪儿。
9/// 一条 `CallEdge` 由两处这样的调用点组成。
10#[derive(Clone, Debug, PartialEq, Eq)]
11pub struct CallSite {
12    /// Registry node the active frame belongs to.
13    /// 当前活动帧所属的注册机节点。
14    pub node: NodeId,
15    /// Logical function name active in that frame.
16    /// 该帧中处于活动状态的逻辑函数名。
17    pub function: &'static str,
18    /// Identifier of the trace frame that observed this call, unique per invocation.
19    /// 观察到本次调用的追踪帧编号,每次调用实例都不同。
20    pub frame_id: u64,
21    /// Stable declaration/callsite location. `None` is reserved for callers
22    /// that construct a synthetic frame directly.
23    /// 稳定的声明/调用位置;`None` 仅保留给直接构造合成帧的调用者。
24    pub source: Option<SourceLocation>,
25}
26
27// ---------------------------------------------------------------------------
28// Observed call edges and evidence. Shared by run_method tracing and
29// debug_method tooling; defined here because they are pure protocol nouns.
30// 已观测调用边与证据。由 run_method 追踪与 debug_method 工具共用;
31// 作为纯协议名词定义在 kernel。
32
33/// One call edge that was observed while a `CallTrace` frame was active.
34/// `CallTrace` 中实际观察到的一条调用边。
35#[derive(Clone, Debug, PartialEq, Eq)]
36pub struct CallEdge {
37    /// Site that observed the call while its frame was active.
38    /// 调用发生、其帧处于活动状态的调用点。
39    pub caller: CallSite,
40    /// Site recorded as the target of that call.
41    /// 被记录为该调用目标的调用点。
42    pub callee: CallSite,
43}
44
45/// Provenance of a relationship across runtime, MIR, and source evidence.
46/// 运行时、MIR 与源码证据共用的关系来源。
47#[derive(Clone, Copy, Debug, PartialEq, Eq)]
48pub enum EvidenceKind {
49    /// Confirmed by a live `CallTrace` observation.
50    /// 由一次实时 `CallTrace` 观测确认。
51    Live,
52    /// Candidate found by source analysis without runtime confirmation.
53    /// 源码分析找到、未经运行期确认的候选。
54    Source,
55    /// Candidate inferred from MIR; it may not have executed.
56    /// 由 MIR 推断出的候选;它可能并未执行。
57    Mir,
58    /// Supplied by an external adapter without a local trace.
59    /// 由外部适配器提供,没有本地追踪。
60    External,
61    /// A relation whose producer is not known.
62    /// 产出方未知的关系。
63    Unknown,
64}
65
66impl EvidenceKind {
67    /// Compact marker used by text, DOT, and Studio renderers.
68    /// 文本、DOT 与 Studio 渲染器共用的紧凑标记。
69    pub const fn marker(self) -> &'static str {
70        match self {
71            Self::Live => "+",
72            Self::Mir => "?",
73            Self::Source => "~",
74            Self::External => "x",
75            Self::Unknown => "!",
76        }
77    }
78
79    /// Stable machine and human readable label.
80    /// 稳定的机器和人类可读标签。
81    pub const fn label(self) -> &'static str {
82        match self {
83            Self::Live => "live",
84            Self::Mir => "mir",
85            Self::Source => "source",
86            Self::External => "external",
87            Self::Unknown => "unknown",
88        }
89    }
90
91    /// Only a live observation confirms that an edge executed.
92    /// 只有 Live 观察能确认边实际执行过。
93    pub const fn confirmed(self) -> bool {
94        matches!(self, Self::Live)
95    }
96}
97
98/// A call edge with invocation IDs removed for topology queries.
99/// 去掉调用实例编号、用于拓扑查询的逻辑调用边。
100#[derive(Clone, Debug, PartialEq, Eq)]
101pub struct LogicalCallEdge {
102    /// Calling side with invocation ids dropped, so repeated calls share one edge.
103    /// 去掉调用实例编号后的调用方,因此重复调用共享同一条边。
104    pub caller: CallSite,
105    /// Called side with invocation ids dropped, so repeated calls share one edge.
106    /// 去掉调用实例编号后的被调用方,因此重复调用共享同一条边。
107    pub callee: CallSite,
108    /// Provenance that justifies treating this edge as real.
109    /// 支撑该边成立的证据来源。
110    pub evidence: EvidenceKind,
111}
112
113// ---------------------------------------------------------------------------
114// Plugin manifests and flow contracts.
115// These types are declared here because `RegistrationInfo`/`RegistrationSnapshot`
116// carry them; the runtime plugin modules re-export them at their historical
117// paths. 以下类型因被注册声明持有而定义在 kernel;runtime 插件模块在原路径重导出。
118
119/// Runtime collection policy.
120/// 运行时追踪收集策略。
121///
122/// `Off` is the release-safe default for runtime traces. `ErrorsOnly`
123/// keeps evidence only for a failed result/panic scope, while `Full` retains
124/// every observed frame, local, and data edge.
125/// `Off` 是运行时追踪的发布安全默认值;`ErrorsOnly` 只保留
126/// 失败结果或 panic 作用域中的证据;`Full` 保留全部帧、局部值和数据边。
127#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
128pub enum TraceMode {
129    /// Do not allocate or retain runtime evidence.
130    /// 不分配也不保留运行时证据。
131    #[default]
132    Off,
133    /// Retain evidence only when an error scope fails.
134    /// 只有错误作用域失败时才保留证据。
135    ErrorsOnly,
136    /// Retain all observed runtime evidence.
137    /// 保留全部观察到的运行时证据。
138    Full,
139}
140
141impl TraceMode {
142    /// Parses the value accepted by `XIRANG_TRACE`.
143    /// 解析 `XIRANG_TRACE` 支持的值。
144    pub fn parse_trace_mode(value: &str) -> Option<Self> {
145        match value.trim().to_ascii_lowercase().as_str() {
146            "off" | "0" | "disabled" => Some(Self::Off),
147            "errors-only" | "errors_only" | "errors" => Some(Self::ErrorsOnly),
148            "full" | "all" => Some(Self::Full),
149            _ => None,
150        }
151    }
152}
153
154#[cfg(test)]
155mod trace_mode_tests {
156    use super::TraceMode;
157
158    #[test]
159    fn parse_accepts_documented_spellings() {
160        assert_eq!(TraceMode::parse_trace_mode("off"), Some(TraceMode::Off));
161        assert_eq!(
162            TraceMode::parse_trace_mode("ERRORS-ONLY"),
163            Some(TraceMode::ErrorsOnly)
164        );
165        assert_eq!(TraceMode::parse_trace_mode(" full "), Some(TraceMode::Full));
166        assert_eq!(TraceMode::parse_trace_mode("sometimes"), None);
167    }
168}