Struct CallTrace 

pub struct CallTrace { /* private fields */ }

The runtime evidence collector shared by frames, locals, and value edges. 运行期证据收集器，由调用帧、局部值与值边共用。

Implementations

impl CallTrace

pub fn new() -> Self

Creates a collector using the application default policy. 使用应用默认策略创建收集器。

Debug builds default to ErrorsOnly; release builds default to Off. 调试构建默认使用 ErrorsOnly，发布构建默认使用 Off。

pub fn runtime() -> Self

Creates a collector using the application default policy. 使用应用默认策略创建收集器。

pub fn disabled() -> Self

Creates a disabled collector with no-op recording methods. 创建关闭收集器，所有记录方法都是 no-op。

pub fn errors_only() -> Self

Creates an errors-only collector. 创建只保留失败证据的收集器。

pub fn full() -> Self

Creates a full collector. 创建完整收集器。

pub fn with_mode(mode: TraceMode) -> Self

Create an empty collector with an explicit collection policy. 以显式收集策略创建一个不含证据的收集器。

pub const fn mode(&self) -> TraceMode

The collection policy currently in force. 当前生效的收集策略。

pub fn set_mode(&mut self, mode: TraceMode)

Changes the policy and clears evidence that no longer matches it. 修改策略，并清理不再符合新策略的证据。

pub const fn is_collecting(&self) -> bool

Whether the current policy records anything, i.e. mode is not Off. 当前策略是否记录任何内容，即 mode 不为 Off。

pub fn clear(&mut self)

Removes all collected evidence without changing the policy. 清除全部已收集证据，但不修改策略。

pub fn with_result<T, E>( &mut self, operation: impl FnOnce(&mut Self) -> Result<T, E>, ) -> Result<T, E>

Runs a fallible operation and commits evidence only when it fails. 执行一个可失败操作，只有失败时才提交追踪证据。

Nested scopes share the outer transaction. This means a successful inner call remains available when its parent later returns Err. 嵌套作用域共享外层事务，因此内部成功但父调用最终失败时，内部证据仍会保留。

pub fn call_edges(&self) -> Vec<CallEdge>

Distinct caller/callee frame pairs, in first-seen order. 去重后的调用者/被调用者帧对，按首次出现顺序排列。

pub fn logical_call_edges(&self) -> Vec<LogicalCallEdge>

Distinct caller/callee function pairs, all labeled live evidence. 去重后的调用者/被调用者函数对，证据类型均标为 live。

Frame identity is dropped on purpose: two calls to the same functions from different frames collapse into one logical edge. 这里刻意丢掉帧身份：不同帧中对同一对函数的两次调用会合并成一条逻辑边。

impl CallTrace

pub fn transform( &mut self, input: LocalId, name: impl Into<String>, type_name: impl Into<String>, value: impl Display, ) -> LocalId

Record input transformed into a new binding; returns the new local. 记录 input 变换出的新绑定，返回新局部值。

The callsite is taken from the caller; in Off mode nothing is recorded and LocalId(0) is returned. 调用点取自调用方；Off 模式下不记录任何内容并返回 LocalId(0)。

pub fn transform_at_callsite( &mut self, input: LocalId, name: impl Into<String>, type_name: impl Into<String>, value: impl Into<String>, file: &'static str, line: u32, column: u32, ) -> LocalId

transform with an explicit callsite for adapters. 带显式调用点的 transform，供适配器使用。

pub fn return_value( &mut self, input: LocalId, name: impl Into<String>, type_name: impl Into<String>, value: impl Display, ) -> LocalId

Record input as returned by the current call; returns the returned local. 记录当前调用返回 input，返回代表返回值的局部值。

pub fn return_at_callsite( &mut self, input: LocalId, name: impl Into<String>, type_name: impl Into<String>, value: impl Into<String>, file: &'static str, line: u32, column: u32, ) -> LocalId

return_value with an explicit callsite for adapters. 带显式调用点的 return_value，供适配器使用。

pub fn consume( &mut self, input: LocalId, function: impl Into<String>, parameter: impl Into<String>, ) -> LocalId

Record input consumed as parameter of function. 记录 input 作为 function 的 parameter 被消费。

Returns the consumer local, which is what later queries see as the downstream end of this edge. 返回消费者局部值，后续查询会把它当作该边的下游端点。

pub fn consume_at_callsite( &mut self, function: impl Into<String>, parameter: impl Into<String>, input: LocalId, file: &'static str, line: u32, column: u32, ) -> LocalId

consume with an explicit callsite for adapters. 带显式调用点的 consume，供适配器使用。

pub fn data_edges(&self) -> &[DataEdge]

All recorded value edges, in insertion order. 按写入顺序返回全部已记录的值边。

pub fn provenance(&self, id: LocalId) -> Vec<&LocalValue>

Every local id transitively depends on, including itself, producers first. id 传递依赖的全部局部值（含自身），生产者在前。

pub fn consumers(&self, id: LocalId) -> Vec<&DataEdge>

Edges that consume id directly, without following them onward. 直接消费 id 的边，不继续向后追踪。

pub fn outgoing(&self, id: LocalId) -> Vec<DataHop<'_>>

Direct consumers of id, each paired with the local it produced. id 的直接消费者，各自与它产出的局部值配对。

pub fn incoming(&self, id: LocalId) -> Vec<DataHop<'_>>

Direct producers of id, each paired with the local it came from. id 的直接生产者，各自与它来自的局部值配对。

pub fn downstream(&self, id: LocalId) -> Vec<&LocalValue>

Every local reachable from id, nearest consumers first, de-duplicated. 从 id 可到达的全部局部值，最近的消费者在前，且不重复。

pub fn render_provenance(&self, id: LocalId) -> String

Render id and its upstream/downstream neighborhood as text. 以文本渲染 id 及其上下游邻域。

An unknown id renders a single local <id> not found line instead of panicking. 未知 id 只渲染一行 local <id> not found，不会 panic。

pub fn render_data_flow(&self) -> String

Render every recorded local and edge as one text block. 把全部已记录局部值与边渲染成一段文本。

impl CallTrace

pub fn with<R>( &mut self, node: NodeId, function: &'static str, operation: impl FnOnce(&mut Self) -> R, ) -> R

Run operation inside a new frame for node/function. 在 node/function 的新调用帧内执行 operation。

The frame is pushed before the callback and popped afterwards, including when it panics, so a stale frame never captures later values. Off mode runs the callback without recording a frame. 回调前压入该帧、之后弹出，panic 时同样弹出，陈旧帧不会捕获后续值。Off 模式只 执行回调而不记录帧。

pub fn with_at<R>( &mut self, node: NodeId, function: &'static str, source: SourceLocation, operation: impl FnOnce(&mut Self) -> R, ) -> R

Record a call with the source line that entered it. 记录调用及其进入位置的源码行。

pub fn frame_depth(&self, frame_id: u64) -> usize

Return the number of caller frames above one invocation. 返回某个调用实例上方的调用帧数量。

pub fn frame_view(&self, frame_id: u64) -> Option<FrameView<'_>>

Borrow one frame and its parent link without allocating. 无分配地借用一个调用帧及其父链接。

pub fn frame_ids(&self) -> impl Iterator<Item = u64> + '_

Iterate frame IDs in recording order for indexed debug views. 按记录顺序遍历帧 ID，供索引型调试视图使用。

pub fn path_for_frame(&self, frame_id: u64) -> Option<Vec<CallSite>>

Materialize only one requested invocation path. 只生成指定调用实例的路径。

pub fn path_iter(&self, frame_id: u64) -> Option<FramePath<'_>>

Borrow one invocation path without allocating a snapshot. 借用一条调用路径，不分配快照。

pub fn current_path_iter(&self) -> Option<FramePath<'_>>

Borrow the currently active path without allocating. 借用当前活动调用路径，不分配临时数组。

pub fn visit_path<F>(&self, frame_id: u64, visit: F) -> bool

where F: FnMut(&CallSite) -> bool,

Visit one invocation path from its root to the selected frame without cloning CallSite values or allocating a temporary path vector. 从根到目标帧访问一条调用路径，不复制 CallSite，也不分配临时路径数组。

The callback runs once per frame. Returning false stops the walk and makes the method return false; this is useful for bounded TUI renders. 回调每帧执行一次；返回 false 会停止遍历并让方法返回 false，适合限制 TUI 输出。

pub fn current_path(&self) -> Vec<CallSite>

Clone the active root-to-leaf call path, outermost frame first. 克隆当前活动的根到叶调用路径，最外层帧在前。

pub fn paths(&self) -> Vec<Vec<CallSite>>

Rebuild paths on demand; the frame arena is the persistent form. 按需重建路径；持久存储形式是帧表。

pub fn paths_iter(&self) -> impl Iterator<Item = Vec<CallSite>> + '_

Lazily yield invocation paths; no path is built before it is requested. 惰性产生调用路径；只有请求某一项时才构造该路径。

pub fn borrowed_paths_iter(&self) -> impl Iterator<Item = FramePath<'_>> + '_

Lazily borrow every recorded path without cloning call sites. 惰性借用所有已记录路径，不复制调用点。

pub fn frame_count(&self) -> usize

Number of persistent call frames, useful for memory/debug audits. 持久化调用帧数量，便于内存和调试审计。

pub fn matching_paths(&self, query: &str) -> Vec<Vec<CallSite>>

Match a function or step name without losing its complete call chain. 按函数或步骤名匹配，同时保留完整调用链。

pub fn matching_paths_iter( &self, query: &str, ) -> impl Iterator<Item = Vec<CallSite>> + '_

Lazily match call paths without materializing unrelated paths. 惰性匹配调用路径，不为无关调用生成路径。

pub fn render_tree(&self) -> String

Render every frame as one indented line, in recording order. 按记录顺序把每个调用帧渲染成一行缩进文本。

impl CallTrace

pub fn local( &mut self, name: impl Into<String>, type_name: impl Into<String>, value: impl Display, kind: LocalKind, ) -> LocalId

Record a local, taking file/line/column from the caller’s location. 记录一个局部值，文件、行、列取自调用方位置。

Returns LocalId(0) and stores nothing when the trace is Off. 追踪为 Off 时不存储任何内容并返回 LocalId(0)。

pub fn local_at( &mut self, name: impl Into<String>, type_name: impl Into<String>, value: impl Into<String>, kind: LocalKind, source: SourceLocation, ) -> LocalId

Record an observed local at an explicit source location. 在显式源码位置记录一个已观测局部值。

pub fn inferred_local( &mut self, function: impl Into<String>, name: impl Into<String>, type_name: impl Into<String>, line: u32, ) -> LocalId

Add a MIR candidate whose runtime value was not observed. 添加运行时未观察到的 MIR 候选局部变量。

pub fn local_at_callsite( &mut self, name: impl Into<String>, type_name: impl Into<String>, value: impl Into<String>, kind: LocalKind, file: &'static str, line: u32, column: u32, ) -> LocalId

Record an observed local with an explicit callsite. 用显式调用点记录一个已观测局部值。

This is the #[track_caller]-free entry point for adapters, and it is what local delegates to; the function name is read from the active frame, or "<local>" outside any traced call. 这是供适配器使用的、不依赖 #[track_caller] 的入口，也是 local 的委托目标； 函数名取自活动帧，不在任何被追踪调用内时为 "<local>"。

pub fn locals(&self) -> &[LocalValue]

Every local recorded so far, in recording order. 按记录顺序返回目前记录的全部局部值。

pub fn path_for_local(&self, id: LocalId) -> Vec<CallSite>

The root-to-leaf call path that encloses id, empty when unknown. 包含 id 的根到叶调用路径；未知时为空。

pub fn find_local(&self, id: LocalId) -> Option<&LocalValue>

Look up one local by id, None when the id describes no live evidence. 按 id 查找一个局部值；该 id 不对应任何现存证据时为 None。

pub fn matching_locals(&self, query: &str) -> Vec<&LocalValue>

Locals matching a case-insensitive name, function, type, or value query. 匹配大小写不敏感的名称、函数、类型或取值查询的局部值。

An empty query returns every local; an exact name or function match wins over the substring search, so a caller sees the precise hit first. 空查询返回全部局部值；名称或函数的精确匹配优先于子串搜索，调用方先看到精确命中。

Trait Implementations

impl Clone for CallTrace

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CallTrace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CallTrace

fn default() -> Self

Returns the “default value” for a type.