Crate borrowscope_runtime

Expand description

§BorrowScope Runtime

A runtime tracking library for visualizing Rust’s ownership and borrowing system.

This crate captures ownership transfers, borrows, and smart pointer operations as they happen at runtime, generating structured event data for analysis.

§Quick Start

use borrowscope_runtime::*;

// Clear previous tracking data
reset();

// Track variable creation
let data = track_new("data", vec![1, 2, 3]);

// Track borrowing
let r = track_borrow("r", &data);
println!("{:?}", r);

// Track drops
track_drop("r");
track_drop("data");

// Export events as JSON
let events = get_events();
println!("{}", serde_json::to_string_pretty(&events).unwrap());

§Feature Flags

track - Enables runtime tracking. Without this feature, all tracking functions compile to no-ops with zero overhead.

[dependencies]
borrowscope-runtime = { version = "0.1", features = ["track"] }

§Modules

Core tracking functions (41 functions for all ownership patterns)
Event types and serialization
Ownership graph building and analysis
JSON export utilities
Lifetime analysis and timeline construction

§Tracking Categories

Category	Functions
Basic ownership	`track_new`, `track_borrow`, `track_borrow_mut`, `track_move`, `track_drop`
RAII guards	`track_new_guard`, `track_borrow_guard`, `track_borrow_mut_guard`
Smart pointers	`track_rc_new`, `track_rc_clone`, `track_arc_new`, `track_arc_clone`
Interior mutability	`track_refcell_`, `track_cell_`
Unsafe code	`track_raw_ptr`, `track_unsafe_`, `track_ffi_call`, `track_transmute`

§RAII Guards

For automatic drop tracking, use the guard variants:

use borrowscope_runtime::*;

reset();
{
    let data = track_new_guard("data", vec![1, 2, 3]);
    println!("{:?}", *data);
    // track_drop("data") called automatically when data goes out of scope
}

let events = get_events();
assert!(events.last().unwrap().is_drop());

§Performance

With track feature: ~75-80ns per tracking call
Without track feature: zero overhead (compiled away)

Macros§

refcell_borrow: Convenience macro for RefCell borrow tracking with auto file:line capture
refcell_borrow_mut: Convenience macro for RefCell borrow_mut tracking with auto file:line capture
refcell_drop: Convenience macro for RefCell drop tracking with auto file:line capture

Structs§

BorrowGuard: RAII guard for borrow tracking (immutable).
BorrowMutGuard: RAII guard for mutable borrow tracking.
ExportData: Complete export format optimized for visualization tools.
ExportEdge: Serializable edge for export.
ExportMetadata: Export metadata with summary statistics.
GraphStats: Graph statistics
LifetimeRelation: A lifetime relationship between a borrower and borrowed variable.
OwnershipGraph: The complete ownership graph built from events.
Timeline: Timeline representation for visualization.
TrackGuard: RAII guard that tracks drop automatically.
TrackingSummary: Summary statistics for tracked events.
Variable: A variable node in the ownership graph.

Enums§

ElisionRule: Lifetime elision rules (for documentation and analysis)
Error: Runtime errors that can occur during tracking or export.
Event: An ownership or borrowing event recorded at runtime.
Relationship: A relationship edge between variables.

Functions§

build_graph: Build a graph from events
export_json: Export current tracking data to JSON file
get_borrow_events: Get all Borrow events (both mutable and immutable).
get_drop_events: Get all Drop events.
get_event_counts: Get count of events by type.
get_events: Get all recorded events.
get_events_filtered: Get events filtered by a predicate.
get_events_for_var: Get events for a specific variable by name.
get_graph: Get the ownership graph built from current events
get_move_events: Get all Move events.
get_new_events: Get all New events.
get_summary: Get a summary of all tracked events.
print_summary: Print a summary of tracked events to stdout.
reset: Reset tracking state.
track_arc_clone: Track Arc::clone operation.
track_arc_clone_with_id: Track Arc::clone with explicit IDs and location (advanced API)
track_arc_new: Track Arc::new allocation.
track_arc_new_with_id: Track Arc::new with explicit ID and location (advanced API)
track_borrow: Track an immutable borrow.
track_borrow_guard: Track an immutable borrow with automatic drop tracking.
track_borrow_mut: Track a mutable borrow.
track_borrow_mut_guard: Track a mutable borrow with automatic drop tracking.
track_borrow_mut_with_id: Track a mutable borrow with full metadata (advanced API)
track_borrow_with_id: Track an immutable borrow with full metadata (advanced API)
track_cell_get: Track Cell::get operation.
track_cell_new: Track Cell::new allocation.
track_cell_set: Track Cell::set operation.
track_const_eval: Track const evaluation.
track_drop: Track a variable going out of scope.
track_drop_batch: Track multiple drops in batch (optimized).
track_drop_with_id: Track a drop with explicit ID and location (advanced API)
track_ffi_call: Track FFI call.
track_move: Track an ownership move.
track_move_with_id: Track a move with explicit IDs and location (advanced API)
track_new: Track a new variable creation.
track_new_guard: Track a new variable with automatic drop tracking.
track_new_with_id: Track a new variable with explicit ID and location (advanced API)
track_raw_ptr: Track raw pointer creation.
track_raw_ptr_deref: Track raw pointer dereference.
track_raw_ptr_mut: Track mutable raw pointer creation.
track_rc_clone: Track Rc::clone operation.
track_rc_clone_with_id: Track Rc::clone with explicit IDs and location (advanced API)
track_rc_new: Track Rc::new allocation.
track_rc_new_with_id: Track Rc::new with explicit ID and location (advanced API)
track_refcell_borrow: Track RefCell::borrow operation.
track_refcell_borrow_mut: Track RefCell::borrow_mut operation.
track_refcell_drop: Track RefCell borrow drop (when Ref/RefMut is dropped).
track_refcell_new: Track RefCell::new allocation.
track_static_access: Track static variable access (read or write).
track_static_init: Track static variable initialization.
track_transmute: Track transmute operation.
track_union_field_access: Track union field access.
track_unsafe_block_enter: Track unsafe block entry.
track_unsafe_block_exit: Track unsafe block exit.
track_unsafe_fn_call: Track unsafe function call.

Type Aliases§

Result: Result type alias

Crate borrowscope_runtime

Crate borrowscope_runtime Copy item path

§BorrowScope Runtime

§Quick Start

§Feature Flags

§Modules

§Tracking Categories

§RAII Guards

§Performance

Macros§

Structs§

Enums§

Functions§

Type Aliases§

Crate borrowscope_runtime