Struct GcRef 

pub struct GcRef<T: GcNode> { /* private fields */ }

Garbage collection reference

Implementations

impl<T: GcNode> GcRef<T>

pub fn try_from_ref(heap: &GcHeap, data_ref: &T) -> Option<Self>

Create GcRef from &T reference

This method verifies that the passed reference comes from a valid GC object. It ensures safety by checking if the corresponding GcHead is in the GC context.

Parameters

• data_ref: Reference to convert, must come from valid GcRef object

Return Value

• Some(GcRef<T>): If reference comes from valid GC object
• None: If reference is not from GC object or object is invalid

Safety

Caller must ensure the passed reference indeed comes from a valid GcRef object.

Examples found in repository

examples/advanced_features.rs (line 245)

fn demonstrate_reference_recovery(
    heap: &mut GcHeap,
    partition: gc_lite::GcPartitionId,
) -> GcResult<()> {
    println!("1. Create object and get reference...");

    let original_ref = unsafe {
        heap.alloc_raw(
            partition,
            TestData {
                value: 42,
                name: "test".to_string(),
            },
        )
    }
    .map_err(|(err, _)| err)?;

    let data_ref = original_ref.deref();
    println!("  Original reference: {:?}", original_ref);
    println!("  Data: {:?}", data_ref);

    // Recover GcRef from reference
    println!("\n2. Recover GcRef from reference...");
    let recovered_ref = GcRef::try_from_ref(heap, data_ref);

    match recovered_ref {
        Some(recovered) => {
            println!("  Recovery successful: {:?}", recovered);
            let recovered_data = recovered.deref();
            println!("  Recovered data: {:?}", recovered_data);
            println!("  Data equal: {}", data_ref == recovered_data);
            println!("  Reference equal: {}", original_ref == recovered);
        }
        None => println!("  Recovery failed (possibly type registration issue)"),
    }

    // Test invalid reference recovery - create an object not in GC heap
    println!("\n3. Test invalid reference recovery...");
    let local_data = TestData {
        value: 100,
        name: "local".to_string(),
    };
    let invalid_result = GcRef::try_from_ref(heap, &local_data);
    println!(
        "  Invalid reference recovery result: {:?} (should be None)",
        invalid_result
    );

    Ok(())
}

pub unsafe fn from_ref_unchecked(data_ref: &T) -> Self

Unsafe conversion from &T to GcRef, main focus on speed.

Safety

Caller must ensure &T comes from GcRef, otherwise consequences are unpredictable.

pub fn with_mut<F, R>(&mut self, heap: &mut GcHeap, mutator: F) -> R

where F: FnOnce(&mut T) -> R,

Examples found in repository

examples/advanced_features.rs (line 132)

fn demonstrate_cyclic_references(
    heap: &mut GcHeap,
    partition: gc_lite::GcPartitionId,
) -> GcResult<()> {
    println!("1. Create circular reference nodes...");

    // Create two mutually referencing nodes
    let mut node1 = unsafe { heap.alloc_root_raw(partition, CyclicNode::new("Node A")) }
        .map_err(|(err, _)| err)?;
    let mut node2 = unsafe { heap.alloc_root_raw(partition, CyclicNode::new("Node B")) }
        .map_err(|(err, _)| err)?;

    // Establish circular references
    {
        node1.with_mut(heap, |n| n.set_partner(node2));
        node2.with_mut(heap, |n| n.set_partner(node1));
    }

    println!("  Created node1: {}", node1.deref());
    println!("  Created node2: {}", node2.deref());

    // Trigger garbage collection
    println!("\n2. Trigger garbage collection (circular references still exist)...");
    let freed = heap.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  回收了 {} 字节内存", freed);

    // Verify circular references still exist
    println!("\n3. Verify circular references...");
    println!("  Node1's partner: {}", node1.get_partner_name());
    println!("  Node2's partner: {}", node2.get_partner_name());

    // Clear root object status, let circular references be collected
    println!("\n4. Clear root object status and trigger GC again...");
    let freed = heap.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!(
        "  Freed {} bytes of memory (circular references correctly collected)",
        freed
    );

    Ok(())
}

/// Demonstrate complex data structures
fn demonstrate_complex_structures(
    heap: &mut GcHeap,
    partition: gc_lite::GcPartitionId,
) -> GcResult<()> {
    println!("1. Create complex data structures...");

    // Create multiple nodes
    let mut root_node =
        unsafe { heap.alloc_root_raw(partition, TreeNode::new("Root")) }.map_err(|(err, _)| err)?;
    let mut child1 =
        unsafe { heap.alloc_raw(partition, TreeNode::new("Child 1")) }.map_err(|(err, _)| err)?;
    let child2 =
        unsafe { heap.alloc_raw(partition, TreeNode::new("Child 2")) }.map_err(|(err, _)| err)?;
    let grandchild = unsafe { heap.alloc_raw(partition, TreeNode::new("Grandchild")) }
        .map_err(|(err, _)| err)?;

    // Build tree structure
    {
        root_node.with_mut(heap, |n| n.add_child(child1));
        root_node.with_mut(heap, |n| n.add_child(child2));
        child1.with_mut(heap, |n| n.add_child(grandchild));
    }

    // Create data container
    let container = unsafe {
        heap.alloc_root_raw(
            partition,
            DataContainer {
                root: root_node,
                metadata: vec![1, 2, 3],
                optional_data: Some(child1),
            },
        )
    }
    .map_err(|(err, _)| err)?;

    println!("  Created tree structure:");
    println!("    Root -> Child 1 -> Grandchild");
    println!("    Root -> Child 2");
    println!("  Created data container");

    // Trigger garbage collection
    println!("\n2. Trigger garbage collection...");
    let freed = heap.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  回收了 {} 字节内存", freed);

    // Verify data structure integrity
    println!("\n3. Verify data structure integrity...");
    {
        println!("  Container root node: {}", container.root.name);
        println!("  Metadata length: {}", container.metadata.len());
        println!(
            "  Optional data exists: {}",
            container.optional_data.is_some()
        );
    }

    Ok(())
}

examples/performance_benchmark.rs (line 122)

fn benchmark_complex_graphs() {
    let sizes = [100, 500, 1000];

    for &size in &sizes {
        println!("\nTest complex object graph size: {} nodes", size);

        let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
        let partition = context.create_partition();

        // Create complex object graph
        let graph_start = Instant::now();
        let mut nodes = Vec::new();

        // Create all nodes
        for _i in 0..size {
            let node = unsafe {
                context.alloc_raw(
                    partition,
                    GraphNode {
                        neighbors: Vec::new(),
                    },
                )
            }
            .unwrap();
            nodes.push(node);
        }

        // Establish complex dependencies
        for i in 0..size {
            {
                // Each node points to subsequent nodes
                for j in 1..=5 {
                    if i + j < size {
                        let n = nodes[i + j];
                        nodes[i].with_mut(&mut context, |node| node.neighbors.push(n));
                    }
                }
                // Every 10 nodes form a cycle
                if i % 10 == 0 && i + 9 < size {
                    let n = nodes[i];
                    nodes[i + 9].with_mut(&mut context, |node| node.neighbors.push(n));
                }
            }
        }
        let graph_duration = graph_start.elapsed();

        println!("  Built complex object graph in: {:?}", graph_duration);

        // Measure GC performance
        let gc_start = Instant::now();
        let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
        let gc_duration = gc_start.elapsed();

        println!("  GC回收 {} 字节耗时: {:?}", freed, gc_duration);
        println!(
            "  Object graph complexity: average {} neighbors per node",
            if size > 0 { (size * 5) / size } else { 0 }
        );
    }
}

examples/basic_usage.rs (line 192)

fn main() -> GcResult<()> {
    println!("=== Basic usage example of partitioned garbage collection system ===");

    // Create garbage collection context
    let mut heap = GcHeap::new(&GC_TYPE_REGISTRY);

    println!("Initial state:");
    println!("  Number of partitions: {}", heap.partition_ids().len());

    // Create two partitions
    println!("\nCreate partitions:");
    let partition1 = heap.create_partition();
    let partition2 = heap.create_partition();
    println!("  Created partition1: {:?}", partition1);
    println!("  Created partition2: {:?}", partition2);
    println!("  Number of partitions: {}", heap.partition_ids().len());

    // Allocate objects in partition1
    println!("\nAllocate objects in partition1:");
    let obj1 = unsafe { heap.alloc_raw(partition1, MyString(String::from("Hello"))) }
        .map_err(|(err, _)| err)?;
    let obj2 = unsafe { heap.alloc_raw(partition1, MyI32(42)) }.map_err(|(err, _)| err)?;
    let obj3 = unsafe { heap.alloc_raw(partition1, MyString(String::from("VectorData"))) }
        .map_err(|(err, _)| err)?;

    println!("  Created string: '{}'", obj1.deref());
    println!("  Created number: {}", obj2.deref());
    println!("  Created string: '{}'", obj3.deref());

    // Allocate objects in partition2
    println!("\nAllocate objects in partition2:");
    let obj4 = unsafe { heap.alloc_raw(partition2, MyString(String::from("World"))) }
        .map_err(|(err, _)| err)?;
    let obj5 = unsafe { heap.alloc_raw(partition2, MyI32(99)) }.map_err(|(err, _)| err)?;

    println!("  Created string: '{}'", obj4.deref());
    println!("  Created number: {}", obj5.deref());

    // Display partition status
    println!("\nPartition status:");
    for partition_id in heap.partition_ids() {
        if let Some(partition) = heap.partition(partition_id) {
            let limit = heap.memory_limit();
            let usage = if limit > 0 {
                format!(
                    "{}/{} bytes ({:.1}%)",
                    partition.memory_used(),
                    limit,
                    (partition.memory_used() as f64 / limit as f64) * 100.0
                )
            } else {
                format!("{}/∞ bytes", partition.memory_used())
            };
            println!(
                "  {:?}: {} [自动GC: {}]",
                partition_id,
                usage,
                if heap.gc_threshold() > 0 {
                    "Enabled"
                } else {
                    "Disabled"
                }
            );
        }
    }

    // Root objects are now implicitly managed by stack variables (e.g., obj1, obj2).
    // No explicit `set_root` calls are needed for them.
    println!("\nRoot objects are held by variables:");
    println!("  Roots: obj1, obj2, obj3, obj4, obj5");

    // Manually trigger garbage collection for partition1
    println!("\nManually trigger garbage collection for partition1...");
    let freed = heap.garbage_collect(partition1, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected {} bytes", freed);

    // Verify root objects are still valid
    println!("\nVerify partition1 root objects are still valid:");
    println!("  Object1: '{}'", obj1.deref());
    println!("  Object2: {}", obj2.deref());

    // Manually trigger garbage collection for partition2
    println!("\nManually trigger garbage collection for partition2...");
    let freed = heap.garbage_collect(partition2, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected {} bytes", freed);

    // Verify partition2 root objects are still valid
    println!("\nVerify partition2 root objects are still valid:");
    println!("  Object4: '{}'", obj4.deref());

    // Trigger garbage collection for partition1 again to collect unreferenced objects
    println!("\nTrigger garbage collection for partition1 again...");
    // obj2 is no longer explicitly un-rooted, but we can simulate it going out of scope
    // to test collection. For this example, we'll just collect other garbage.
    let freed = heap.garbage_collect(partition1, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected {} bytes", freed);

    // Verify remaining root objects are still valid
    println!("\nVerify remaining root objects are still valid:");
    println!("  Object1: '{}'", obj1.deref());
    println!("  Object2: {} (still a root)", obj2.deref());

    // Demonstrate automatic garbage collection
    println!("\nDemonstrate automatic garbage collection...");

    // Create a small partition to demonstrate automatic GC
    let small_partition = heap.create_partition();

    // Allocate multiple objects to fill partition
    for i in 0..5 {
        let _obj = unsafe { heap.alloc_raw(small_partition, MyString(format!("Object {}", i))) }
            .map_err(|(err, _)| err)?;
    }

    println!("  Allocated 5 objects in small partition");

    // Demonstrate weak references
    println!("\nDemonstrate weak references:");
    let weak_ref = heap.downgrade(&obj1);
    println!("  Created weak reference: {:?}", weak_ref);

    // Upgrade weak reference
    match weak_ref.upgrade(&heap) {
        Some(strong_ref) => {
            println!(
                "  Weak reference upgrade successful: '{}'",
                strong_ref.deref()
            );
        }
        None => {
            println!("  Weak reference upgrade failed");
        }
    }

    // Demonstrate complex types with GC references
    println!("\nDemonstrate complex types with GC references:");
    let mut node1 =
        unsafe { heap.alloc_raw(partition1, TestNode::new("Node 1")) }.map_err(|(err, _)| err)?;
    let mut node2 =
        unsafe { heap.alloc_raw(partition1, TestNode::new("Node 2")) }.map_err(|(err, _)| err)?;

    // Establish references between nodes
    {
        node1.with_mut(&mut heap, |n| n.add_child(node2));
        node2.with_mut(&mut heap, |n| n.add_child(node1));
    }

    println!("  Created node1: {}", node1.deref());
    println!("  Created node2: {}", node2.deref());

    // Trigger garbage collection, verify circular references are handled correctly
    println!("\nGarbage collection for handling circular references...");
    let freed = heap.garbage_collect(partition1, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  回收了 {} 字节内存", freed);

    // Demonstrate partition deletion
    println!("\nDemonstrate partition deletion:");

    // Create an empty partition
    let empty_partition = heap.create_partition();
    println!("  Created empty partition: {:?}", empty_partition);

    // Delete empty partition
    heap.remove_partition(empty_partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Deleted empty partition successfully");

    // Delete non-empty partition
    heap.remove_partition(partition1, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Deleted non-empty partition successfully");

    println!("\nExample completed!");
    Ok(())
}

pub fn as_ptr(&self) -> NonNull<T>

pub fn downgrade(&self, heap: &mut GcHeap) -> GcWeak<T>

pub fn is_root(&self) -> bool

check if this is root object

pub fn node_ptr(&self) -> NonNull<GcHead>

get node raw pointer

Examples found in repository

examples/advanced_features.rs (line 305)

fn demonstrate_cross_context_detection() -> GcResult<()> {
    println!("1. Create two independent heaps...");

    let mut heap1 = new_heap();
    let mut heap2 = new_heap();

    let partition1 = heap1.create_partition();
    let partition2 = heap2.create_partition();

    let obj1 = unsafe {
        heap1.alloc_root_raw(
            partition1,
            TestData {
                value: 1,
                name: "obj1".to_string(),
            },
        )
    }
    .map_err(|(e, _)| e)?;
    let obj2 = unsafe {
        heap2.alloc_raw(
            partition2,
            TestData {
                value: 2,
                name: "obj2".to_string(),
            },
        )
    }
    .map_err(|(e, _)| e)?;

    println!("2. Test object source detection...");
    assert!(heap1.contains(obj1.node_ptr()), "obj1 should be from heap1");
    assert!(
        !heap1.contains(obj2.node_ptr()),
        "obj2 should not be from heap1"
    );
    assert!(heap2.contains(obj2.node_ptr()), "obj2 should be from heap2");
    assert!(
        !heap2.contains(obj1.node_ptr()),
        "obj1 should not be from heap2"
    );

    println!("  ✓ Cross-context detection correct");

    // Clean up
    heap1.garbage_collect(partition1, GcHeap::DUMMY_DISPOSE_CALLBACK);
    heap2.garbage_collect(partition2, GcHeap::DUMMY_DISPOSE_CALLBACK);

    Ok(())
}

pub fn node_info(&self) -> &GcHead

get node info

Trait Implementations

impl<T: GcNode> Clone for GcRef<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: GcNode> Debug for GcRef<T>

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

Formats the value using the given formatter.

impl<T: GcNode> Deref for GcRef<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: GcNode> DerefMut for GcRef<T>

fn deref_mut(&mut self) -> &mut Self::Target

FIXME: DerefMut breaks gc node write barrier. This should be disabled.

impl<T: GcNode> From<&GcRef<T>> for NonNull<GcHead>

fn from(r: &GcRef<T>) -> Self

Converts to this type from the input type.

impl<T: GcNode> From<GcRef<T>> for NonNull<GcHead>

fn from(r: GcRef<T>) -> Self

Converts to this type from the input type.

impl<T: GcNode> PartialEq for GcRef<T>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: GcNode> Copy for GcRef<T>

impl<T: GcNode> Eq for GcRef<T>