Crate borrowscope_runtime 

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