Struct GcRef 

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

Garbage collection reference

Implementations

impl<T: GcNode> GcRef<T>

pub unsafe fn as_ref(&self) -> &T

Access the underlying GC-managed object as a reference.

Safety

The caller must ensure the GC object is still alive and has not been collected (e.g., it is protected by a root/LOCAL flag, or the GC heap is guaranteed not to run a collection cycle).

Examples found in repository

examples/gc_node_usage.rs (line 66)

fn main() -> GcResult<()> {
    let mut heap = GcHeap::new(&GC_TYPE_REGISTRY);
    let partition = heap.create_partition(64 * 1024, 16 * 1024);
    let stack_id = heap.acquire_scope_stack(partition);

    let static_ref = alloc_static(&mut heap, stack_id, 10)?;
    let other_ref = alloc_other(&mut heap, stack_id, 20)?;

    println!(
        "Static node value: {}",
        unsafe { static_ref.as_ref() }._value
    );
    println!("Other node value: {}", unsafe { other_ref.as_ref() }._value);

    heap.release_scope_stack(stack_id);

    println!("gc_node_usage example verified");

    Ok(())
}

examples/advanced_features.rs (line 138)

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
    {
        unsafe {
            node1.with_write_barrier(heap, |n| n.set_partner(node2));
        }
        unsafe {
            node2.with_write_barrier(heap, |n| n.set_partner(node1));
        }
    }

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

    // 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: {}",
        unsafe { node1.as_ref() }.get_partner_name()
    );
    println!(
        "  Node2's partner: {}",
        unsafe { node2.as_ref() }.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
    {
        unsafe {
            root_node.with_write_barrier(heap, |n| n.add_child(child1));
        }
        unsafe {
            root_node.with_write_barrier(heap, |n| n.add_child(child2));
        }
        unsafe {
            child1.with_write_barrier(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...");
    {
        let container_ref = unsafe { container.as_ref() };
        println!(
            "  Container root node: {}",
            unsafe { container_ref.root.as_ref() }.name
        );
        println!("  Metadata length: {}", container_ref.metadata.len());
        println!(
            "  Optional data exists: {}",
            container_ref.optional_data.is_some()
        );
    }

    Ok(())
}

/// Demonstrate reference recovery functionality
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 = unsafe { original_ref.as_ref() };
    println!("  Original reference: {:?}", original_ref);
    println!("  Data: {:?}", data_ref);

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

    match recovered_ref {
        Some(recovered) => {
            println!("  Recovery successful: {:?}", recovered);
            let recovered_data = unsafe { recovered.as_ref() };
            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 = unsafe { GcRef::try_from_ref(heap, &local_data) };
    println!(
        "  Invalid reference recovery result: {:?} (should be None)",
        invalid_result
    );

    Ok(())
}

/// Demonstrate cross-context detection
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(64 * 1024, 16 * 1024);
    let partition2 = heap2.create_partition(64 * 1024, 16 * 1024);

    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(())
}

// Supporting type definitions

/// Circular reference node
#[derive(Debug)]
struct CyclicNode {
    name: String,
    partner: Option<GcRef<CyclicNode>>,
}

impl CyclicNode {
    fn new(name: &str) -> Self {
        Self {
            name: name.to_string(),
            partner: None,
        }
    }

    fn set_partner(&mut self, partner: GcRef<CyclicNode>) {
        self.partner = Some(partner);
    }

    fn get_partner_name(&self) -> String {
        self.partner
            .map(|p| unsafe { p.as_ref() }.name.clone())
            .unwrap_or_else(|| "None".to_string())
    }

examples/basic_usage.rs (line 72)

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(64 * 1024, 16 * 1024);
    let partition2 = heap.create_partition(64 * 1024, 16 * 1024);
    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: '{}'", unsafe { obj1.as_ref() });
    println!("  Created number: {}", unsafe { obj2.as_ref() });
    println!("  Created string: '{}'", unsafe { obj3.as_ref() });

    // 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: '{}'", unsafe { obj4.as_ref() });
    println!("  Created number: {}", unsafe { obj5.as_ref() });

    // 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: '{}'", unsafe { obj1.as_ref() });
    println!("  Object2: {}", unsafe { obj2.as_ref() });

    // 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: '{}'", unsafe { obj4.as_ref() });

    // 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: '{}'", unsafe { obj1.as_ref() });
    println!("  Object2: {} (still a root)", unsafe { obj2.as_ref() });

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

    // Create a small partition to demonstrate automatic GC
    let small_partition = heap.create_partition(64 * 1024, 16 * 1024);

    // 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);
        }
        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
    {
        unsafe {
            node1.with_write_barrier(&mut heap, |n| n.add_child(node2));
        }
        unsafe {
            node2.with_write_barrier(&mut heap, |n| n.add_child(node1));
        }
    }

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

    // 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(64 * 1024, 16 * 1024);
    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 unsafe fn as_mut(&mut self) -> &mut T

Access the underlying GC-managed object as a mutable reference.

Safety

Same as as_ref.

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

Create GcRef from &T reference

Safety

Caller must ensure the passed reference comes from a valid GC-managed object that was allocated via GcRef<T>. Passing a reference from any other source (stack, heap, etc.) is undefined behavior.

Examples found in repository

examples/advanced_features.rs (line 263)

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 = unsafe { original_ref.as_ref() };
    println!("  Original reference: {:?}", original_ref);
    println!("  Data: {:?}", data_ref);

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

    match recovered_ref {
        Some(recovered) => {
            println!("  Recovery successful: {:?}", recovered);
            let recovered_data = unsafe { recovered.as_ref() };
            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 = unsafe { 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 unsafe fn with_write_barrier<F, R>( &mut self, heap: &mut GcHeap, mutator: F, ) -> R

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

Apply a mutator function to the GC-managed object, with write barrier.

Safety

The caller must ensure the GC object is still alive and valid. If the mutator writes new GC references into the object, the write barrier will handle tri-color invariant for incremental GC.

Examples found in repository

examples/advanced_features.rs (line 131)

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
    {
        unsafe {
            node1.with_write_barrier(heap, |n| n.set_partner(node2));
        }
        unsafe {
            node2.with_write_barrier(heap, |n| n.set_partner(node1));
        }
    }

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

    // 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: {}",
        unsafe { node1.as_ref() }.get_partner_name()
    );
    println!(
        "  Node2's partner: {}",
        unsafe { node2.as_ref() }.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
    {
        unsafe {
            root_node.with_write_barrier(heap, |n| n.add_child(child1));
        }
        unsafe {
            root_node.with_write_barrier(heap, |n| n.add_child(child2));
        }
        unsafe {
            child1.with_write_barrier(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...");
    {
        let container_ref = unsafe { container.as_ref() };
        println!(
            "  Container root node: {}",
            unsafe { container_ref.root.as_ref() }.name
        );
        println!("  Metadata length: {}", container_ref.metadata.len());
        println!(
            "  Optional data exists: {}",
            container_ref.optional_data.is_some()
        );
    }

    Ok(())
}

examples/performance_benchmark.rs (line 124)

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(64 * 1024, 16 * 1024);

        // 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];
                        unsafe {
                            nodes[i]
                                .with_write_barrier(&mut context, |node| node.neighbors.push(n));
                        }
                    }
                }
                // Every 10 nodes form a cycle
                if i % 10 == 0 && i + 9 < size {
                    let n = nodes[i];
                    unsafe {
                        nodes[i + 9]
                            .with_write_barrier(&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 188)

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(64 * 1024, 16 * 1024);
    let partition2 = heap.create_partition(64 * 1024, 16 * 1024);
    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: '{}'", unsafe { obj1.as_ref() });
    println!("  Created number: {}", unsafe { obj2.as_ref() });
    println!("  Created string: '{}'", unsafe { obj3.as_ref() });

    // 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: '{}'", unsafe { obj4.as_ref() });
    println!("  Created number: {}", unsafe { obj5.as_ref() });

    // 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: '{}'", unsafe { obj1.as_ref() });
    println!("  Object2: {}", unsafe { obj2.as_ref() });

    // 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: '{}'", unsafe { obj4.as_ref() });

    // 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: '{}'", unsafe { obj1.as_ref() });
    println!("  Object2: {} (still a root)", unsafe { obj2.as_ref() });

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

    // Create a small partition to demonstrate automatic GC
    let small_partition = heap.create_partition(64 * 1024, 16 * 1024);

    // 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);
        }
        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
    {
        unsafe {
            node1.with_write_barrier(&mut heap, |n| n.add_child(node2));
        }
        unsafe {
            node2.with_write_barrier(&mut heap, |n| n.add_child(node1));
        }
    }

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

    // 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(64 * 1024, 16 * 1024);
    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 unsafe fn as_ptr(&self) -> NonNull<T>

Get a raw pointer to the GC-managed payload.

Safety

The caller must ensure the GC object is still alive.

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

Create a weak reference from this GC reference.

Safety

The caller must ensure the GC object is still alive.

pub unsafe fn is_root(&self) -> bool

Check if this is a root object.

Safety

The caller must ensure the GC object is still alive.

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

Get node raw pointer (always safe — just returns the raw pointer value).

Examples found in repository

examples/advanced_features.rs (line 323)

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(64 * 1024, 16 * 1024);
    let partition2 = heap2.create_partition(64 * 1024, 16 * 1024);

    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 unsafe fn node_info(&self) -> &GcHead

Get node info (GC head metadata).

Safety

The caller must ensure the GC object is still alive.

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> Copy for GcRef<T>

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

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

Formats the value using the given formatter.

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

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

Equality operator ==.

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

Inequality operator !=.