Struct GcHeap 

pub struct GcHeap { /* private fields */ }

Implementations

impl GcHeap

pub const DUMMY_DISPOSE_CALLBACK: fn(&GcHeap, &GcHead)

pub fn new(registry: &'static GcTypeRegistry) -> Self

Create a new garbage collection heap with an explicit GC type registry.

The heap starts with no partitions. Use create_partition to add partitions as needed.

Examples found in repository

examples/advanced_features.rs (line 42)

fn new_heap() -> GcHeap {
    GcHeap::new(&GC_TYPE_REGISTRY)
}

examples/gc_node_usage.rs (line 57)

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/performance_benchmark.rs (line 44)

fn benchmark_object_sizes() {
    let sizes = [10, 100, 500, 1000, 5000];

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

        let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
        let partition = context.create_partition(64 * 1024, 16 * 1024);

        // Measure allocation performance
        let alloc_start = Instant::now();
        let mut objects = Vec::new();
        for _i in 0..size {
            let node = unsafe {
                context.alloc_raw(
                    partition,
                    SimpleNode {
                        _data: vec![0u8; 100],
                    },
                )
            } // Each node 100 bytes
            .unwrap();
            objects.push(node);
        }
        let alloc_duration = alloc_start.elapsed();

        println!("  Allocated {} objects in: {:?}", size, alloc_duration);
        println!(
            "  Average allocation time per object: {:?}",
            alloc_duration / size as u32
        );

        // Measure GC performance (all objects can be collected)
        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!(
            "  Average collection time per byte: {:?}",
            if freed > 0 {
                gc_duration / freed as u32
            } else {
                Duration::from_nanos(0)
            }
        );
    }
}

/// Test GC performance of complex object graphs
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 }
        );
    }
}

/// Test memory usage efficiency
fn benchmark_memory_efficiency() {
    println!("\nTesting memory usage efficiency...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024 * 1024); // 1MB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate many small objects
    let small_objects_count = 1000;
    let mut small_objects = Vec::new();

    for _i in 0..small_objects_count {
        let obj = unsafe { context.alloc_raw(partition, SmallData {}) }.unwrap();
        small_objects.push(obj);
    }

    if let Some(partition_info) = context.partition(partition) {
        let used = partition_info.memory_used();
        let limit = context.memory_limit();
        let efficiency = if limit > 0 {
            (used as f64 / limit as f64) * 100.0
        } else {
            0.0
        };

        println!("  After allocating {} small objects:", small_objects_count);
        println!(
            "  Memory usage: {}/{} bytes ({:.1}%)",
            used, limit, efficiency
        );
        println!(
            "  Average overhead per object: {} bytes",
            if small_objects_count > 0 {
                used / small_objects_count
            } else {
                0
            }
        );
    }

    // Collect all objects
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected all objects, freed {} bytes", freed);

    // Verify complete memory collection
    if let Some(partition_info) = context.partition(partition) {
        let used_after = partition_info.memory_used();
        println!("  Memory usage after collection: {} bytes", used_after);
        println!(
            "  Memory collection rate: {:.1}%",
            if freed > 0 {
                (freed as f64 / (freed + used_after) as f64) * 100.0
            } else {
                0.0
            }
        );
    }
}

/// Test automatic GC threshold performance
fn benchmark_auto_gc_threshold() {
    println!("\nTesting automatic GC threshold performance...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Set automatic GC threshold to 1.5KB
    context.set_gc_threshold(1500);

    // Allocate objects until automatic GC is triggered
    let mut allocated_bytes = 0;
    let mut object_count = 0;

    println!("  Allocating objects until automatic GC is triggered...");

    for _i in 0..100 {
        // Try at most 100 times
        // Allocate objects of about 100 bytes
        let node = SimpleNode {
            _data: vec![0u8; 100],
        };
        match unsafe { context.alloc_raw(partition, node) } {
            Ok(_gc_ref) => {
                allocated_bytes += 100 + std::mem::size_of::<GcRef<SimpleNode>>(); // Estimated size
                object_count += 1;

                // Check if approaching threshold
                if let Some(partition_info) = context.partition(partition)
                    && partition_info.memory_used() >= 1500
                {
                    println!(
                        "  Reached automatic GC threshold, allocated {} objects",
                        object_count
                    );
                    println!("  Estimated allocated memory: {} bytes", allocated_bytes);
                    println!(
                        "  Actual memory usage: {} bytes",
                        partition_info.memory_used()
                    );
                    break;
                }
            }
            Err(_) => {
                println!("  Allocation failed, automatic GC may have been triggered");
                break;
            }
        }
    }

    // Manually trigger GC to see effect
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Manual GC freed {} bytes", freed);
}

examples/error_handling.rs (line 37)

fn demonstrate_out_of_memory() -> GcResult<()> {
    println!("1. Create limited memory partition...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate first large object (1KB + header)
    println!("2. Allocate first large object...");
    let gc1: GcRef<LargeData> =
        match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
            Ok(gc_ref) => {
                println!("  ✓ Successfully allocated first object (1KB)");
                gc_ref
            }
            Err((error, _)) => {
                println!("  ✗ First object allocation failed: {:?}", error);
                return Ok(());
            }
        };

    // Allocate second large object (1KB + header) - should exceed 2KB limit
    println!("3. Try to allocate second large object...");
    match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
        Err((GcError::PartitionFull, _)) => {
            println!("  ✓ Correctly detected partition full error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition full error, but allocation succeeded");
            return Ok(());
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition full error, but got: {:?}",
                other_error
            );
            return Ok(());
        }
    }

    // Clean up - through garbage collection instead of manual release
    println!("  ✓ Automatic cleanup through GC");
    context.garbage_collect(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);

    Ok(())
}

/// Demonstrate partition management errors
fn demonstrate_partition_management_errors() -> GcResult<()> {
    println!("1. Test non-existent partition operations...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    let invalid_partition = gc_lite::GcPartitionId(9999); // Non-existent partition

    // Test allocating objects in non-existent partition
    match unsafe {
        context.alloc_raw(
            invalid_partition,
            TestData {
                value: 42,
                name: "test".to_string(),
            },
        )
    } {
        Err((GcError::PartitionNotFound, _)) => {
            println!("  ✓ Allocating objects in non-existent partition returns correct error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition not found error, but allocation succeeded");
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition not found error, but got: {:?}",
                other_error
            );
        }
    }

    // Test getting non-existent partition information
    let partition_info = context.partition(invalid_partition);
    assert!(
        partition_info.is_none(),
        "Non-existent partition should return None"
    );
    println!("  ✓ Getting non-existent partition info returns None");

    // Test removing non-existent partition (remove_partition doesn't return error, just silently fails)
    context.remove_partition(invalid_partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Removing non-existent partition silently fails");

    println!("\n2. Test non-empty partition deletion...");
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate objects in partition
    let obj = unsafe {
        context.alloc_raw(
            partition_id,
            TestData {
                value: 1,
                name: "obj".to_string(),
            },
        )
    }
    .unwrap();
    let _ = obj;

    // Try to delete non-empty partition (remove_partition will force cleanup)
    context.remove_partition(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Successfully deleted non-empty partition (root objects were force cleaned)");

    Ok(())
}

/// Demonstrate GC threshold API errors
fn demonstrate_gc_threshold_errors() -> GcResult<()> {
    println!("1. Test GC threshold API...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024);
    let _partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Test default values
    println!("2. Test default threshold...");
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Default threshold is 0, automatic GC disabled");

    // Test setting threshold
    println!("3. Test setting threshold...");
    context.set_gc_threshold(512);
    assert_eq!(context.gc_threshold(), 512);
    println!("  ✓ Successfully set threshold to 512, automatic GC enabled");

    // Test setting threshold exceeding memory limit
    println!("4. Test setting threshold exceeding memory limit...");
    context.set_gc_threshold(2048);
    // Since threshold exceeds memory limit, will be capped at 0.8x of limit (1024 * 8 / 10 = 819)
    assert_eq!(context.gc_threshold(), 819);
    println!(
        "  ✓ Setting threshold exceeding memory limit automatically adjusted to 0.8x of memory limit"
    );

    // Test disabling automatic GC
    println!("5. Test disabling automatic GC...");
    context.set_gc_threshold(0);
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Successfully disabled automatic GC, threshold set to 0");

    Ok(())
}

examples/basic_usage.rs (line 51)

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 const fn opaque(&self) -> *mut u8

pub const fn set_opaque(&mut self, opaque: *mut u8)

pub fn memory_limit(&self) -> usize

Examples found in repository

examples/performance_benchmark.rs (line 174)

fn benchmark_memory_efficiency() {
    println!("\nTesting memory usage efficiency...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024 * 1024); // 1MB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate many small objects
    let small_objects_count = 1000;
    let mut small_objects = Vec::new();

    for _i in 0..small_objects_count {
        let obj = unsafe { context.alloc_raw(partition, SmallData {}) }.unwrap();
        small_objects.push(obj);
    }

    if let Some(partition_info) = context.partition(partition) {
        let used = partition_info.memory_used();
        let limit = context.memory_limit();
        let efficiency = if limit > 0 {
            (used as f64 / limit as f64) * 100.0
        } else {
            0.0
        };

        println!("  After allocating {} small objects:", small_objects_count);
        println!(
            "  Memory usage: {}/{} bytes ({:.1}%)",
            used, limit, efficiency
        );
        println!(
            "  Average overhead per object: {} bytes",
            if small_objects_count > 0 {
                used / small_objects_count
            } else {
                0
            }
        );
    }

    // Collect all objects
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected all objects, freed {} bytes", freed);

    // Verify complete memory collection
    if let Some(partition_info) = context.partition(partition) {
        let used_after = partition_info.memory_used();
        println!("  Memory usage after collection: {} bytes", used_after);
        println!(
            "  Memory collection rate: {:.1}%",
            if freed > 0 {
                (freed as f64 / (freed + used_after) as f64) * 100.0
            } else {
                0.0
            }
        );
    }
}

examples/basic_usage.rs (line 89)

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 fn set_memory_limit(&mut self, limit: usize) -> usize

Examples found in repository

examples/error_handling.rs (line 38)

fn demonstrate_out_of_memory() -> GcResult<()> {
    println!("1. Create limited memory partition...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate first large object (1KB + header)
    println!("2. Allocate first large object...");
    let gc1: GcRef<LargeData> =
        match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
            Ok(gc_ref) => {
                println!("  ✓ Successfully allocated first object (1KB)");
                gc_ref
            }
            Err((error, _)) => {
                println!("  ✗ First object allocation failed: {:?}", error);
                return Ok(());
            }
        };

    // Allocate second large object (1KB + header) - should exceed 2KB limit
    println!("3. Try to allocate second large object...");
    match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
        Err((GcError::PartitionFull, _)) => {
            println!("  ✓ Correctly detected partition full error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition full error, but allocation succeeded");
            return Ok(());
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition full error, but got: {:?}",
                other_error
            );
            return Ok(());
        }
    }

    // Clean up - through garbage collection instead of manual release
    println!("  ✓ Automatic cleanup through GC");
    context.garbage_collect(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);

    Ok(())
}

/// Demonstrate partition management errors
fn demonstrate_partition_management_errors() -> GcResult<()> {
    println!("1. Test non-existent partition operations...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    let invalid_partition = gc_lite::GcPartitionId(9999); // Non-existent partition

    // Test allocating objects in non-existent partition
    match unsafe {
        context.alloc_raw(
            invalid_partition,
            TestData {
                value: 42,
                name: "test".to_string(),
            },
        )
    } {
        Err((GcError::PartitionNotFound, _)) => {
            println!("  ✓ Allocating objects in non-existent partition returns correct error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition not found error, but allocation succeeded");
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition not found error, but got: {:?}",
                other_error
            );
        }
    }

    // Test getting non-existent partition information
    let partition_info = context.partition(invalid_partition);
    assert!(
        partition_info.is_none(),
        "Non-existent partition should return None"
    );
    println!("  ✓ Getting non-existent partition info returns None");

    // Test removing non-existent partition (remove_partition doesn't return error, just silently fails)
    context.remove_partition(invalid_partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Removing non-existent partition silently fails");

    println!("\n2. Test non-empty partition deletion...");
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate objects in partition
    let obj = unsafe {
        context.alloc_raw(
            partition_id,
            TestData {
                value: 1,
                name: "obj".to_string(),
            },
        )
    }
    .unwrap();
    let _ = obj;

    // Try to delete non-empty partition (remove_partition will force cleanup)
    context.remove_partition(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Successfully deleted non-empty partition (root objects were force cleaned)");

    Ok(())
}

/// Demonstrate GC threshold API errors
fn demonstrate_gc_threshold_errors() -> GcResult<()> {
    println!("1. Test GC threshold API...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024);
    let _partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Test default values
    println!("2. Test default threshold...");
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Default threshold is 0, automatic GC disabled");

    // Test setting threshold
    println!("3. Test setting threshold...");
    context.set_gc_threshold(512);
    assert_eq!(context.gc_threshold(), 512);
    println!("  ✓ Successfully set threshold to 512, automatic GC enabled");

    // Test setting threshold exceeding memory limit
    println!("4. Test setting threshold exceeding memory limit...");
    context.set_gc_threshold(2048);
    // Since threshold exceeds memory limit, will be capped at 0.8x of limit (1024 * 8 / 10 = 819)
    assert_eq!(context.gc_threshold(), 819);
    println!(
        "  ✓ Setting threshold exceeding memory limit automatically adjusted to 0.8x of memory limit"
    );

    // Test disabling automatic GC
    println!("5. Test disabling automatic GC...");
    context.set_gc_threshold(0);
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Successfully disabled automatic GC, threshold set to 0");

    Ok(())
}

examples/performance_benchmark.rs (line 160)

fn benchmark_memory_efficiency() {
    println!("\nTesting memory usage efficiency...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024 * 1024); // 1MB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate many small objects
    let small_objects_count = 1000;
    let mut small_objects = Vec::new();

    for _i in 0..small_objects_count {
        let obj = unsafe { context.alloc_raw(partition, SmallData {}) }.unwrap();
        small_objects.push(obj);
    }

    if let Some(partition_info) = context.partition(partition) {
        let used = partition_info.memory_used();
        let limit = context.memory_limit();
        let efficiency = if limit > 0 {
            (used as f64 / limit as f64) * 100.0
        } else {
            0.0
        };

        println!("  After allocating {} small objects:", small_objects_count);
        println!(
            "  Memory usage: {}/{} bytes ({:.1}%)",
            used, limit, efficiency
        );
        println!(
            "  Average overhead per object: {} bytes",
            if small_objects_count > 0 {
                used / small_objects_count
            } else {
                0
            }
        );
    }

    // Collect all objects
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected all objects, freed {} bytes", freed);

    // Verify complete memory collection
    if let Some(partition_info) = context.partition(partition) {
        let used_after = partition_info.memory_used();
        println!("  Memory usage after collection: {} bytes", used_after);
        println!(
            "  Memory collection rate: {:.1}%",
            if freed > 0 {
                (freed as f64 / (freed + used_after) as f64) * 100.0
            } else {
                0.0
            }
        );
    }
}

/// Test automatic GC threshold performance
fn benchmark_auto_gc_threshold() {
    println!("\nTesting automatic GC threshold performance...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Set automatic GC threshold to 1.5KB
    context.set_gc_threshold(1500);

    // Allocate objects until automatic GC is triggered
    let mut allocated_bytes = 0;
    let mut object_count = 0;

    println!("  Allocating objects until automatic GC is triggered...");

    for _i in 0..100 {
        // Try at most 100 times
        // Allocate objects of about 100 bytes
        let node = SimpleNode {
            _data: vec![0u8; 100],
        };
        match unsafe { context.alloc_raw(partition, node) } {
            Ok(_gc_ref) => {
                allocated_bytes += 100 + std::mem::size_of::<GcRef<SimpleNode>>(); // Estimated size
                object_count += 1;

                // Check if approaching threshold
                if let Some(partition_info) = context.partition(partition)
                    && partition_info.memory_used() >= 1500
                {
                    println!(
                        "  Reached automatic GC threshold, allocated {} objects",
                        object_count
                    );
                    println!("  Estimated allocated memory: {} bytes", allocated_bytes);
                    println!(
                        "  Actual memory usage: {} bytes",
                        partition_info.memory_used()
                    );
                    break;
                }
            }
            Err(_) => {
                println!("  Allocation failed, automatic GC may have been triggered");
                break;
            }
        }
    }

    // Manually trigger GC to see effect
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Manual GC freed {} bytes", freed);
}

pub fn gc_threshold(&self) -> usize

Examples found in repository

examples/error_handling.rs (line 157)

fn demonstrate_gc_threshold_errors() -> GcResult<()> {
    println!("1. Test GC threshold API...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024);
    let _partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Test default values
    println!("2. Test default threshold...");
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Default threshold is 0, automatic GC disabled");

    // Test setting threshold
    println!("3. Test setting threshold...");
    context.set_gc_threshold(512);
    assert_eq!(context.gc_threshold(), 512);
    println!("  ✓ Successfully set threshold to 512, automatic GC enabled");

    // Test setting threshold exceeding memory limit
    println!("4. Test setting threshold exceeding memory limit...");
    context.set_gc_threshold(2048);
    // Since threshold exceeds memory limit, will be capped at 0.8x of limit (1024 * 8 / 10 = 819)
    assert_eq!(context.gc_threshold(), 819);
    println!(
        "  ✓ Setting threshold exceeding memory limit automatically adjusted to 0.8x of memory limit"
    );

    // Test disabling automatic GC
    println!("5. Test disabling automatic GC...");
    context.set_gc_threshold(0);
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Successfully disabled automatic GC, threshold set to 0");

    Ok(())
}

examples/basic_usage.rs (line 104)

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 fn set_gc_threshold(&mut self, threshold: usize) -> usize

Examples found in repository

examples/error_handling.rs (line 162)

fn demonstrate_gc_threshold_errors() -> GcResult<()> {
    println!("1. Test GC threshold API...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024);
    let _partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Test default values
    println!("2. Test default threshold...");
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Default threshold is 0, automatic GC disabled");

    // Test setting threshold
    println!("3. Test setting threshold...");
    context.set_gc_threshold(512);
    assert_eq!(context.gc_threshold(), 512);
    println!("  ✓ Successfully set threshold to 512, automatic GC enabled");

    // Test setting threshold exceeding memory limit
    println!("4. Test setting threshold exceeding memory limit...");
    context.set_gc_threshold(2048);
    // Since threshold exceeds memory limit, will be capped at 0.8x of limit (1024 * 8 / 10 = 819)
    assert_eq!(context.gc_threshold(), 819);
    println!(
        "  ✓ Setting threshold exceeding memory limit automatically adjusted to 0.8x of memory limit"
    );

    // Test disabling automatic GC
    println!("5. Test disabling automatic GC...");
    context.set_gc_threshold(0);
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Successfully disabled automatic GC, threshold set to 0");

    Ok(())
}

examples/performance_benchmark.rs (line 224)

fn benchmark_auto_gc_threshold() {
    println!("\nTesting automatic GC threshold performance...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Set automatic GC threshold to 1.5KB
    context.set_gc_threshold(1500);

    // Allocate objects until automatic GC is triggered
    let mut allocated_bytes = 0;
    let mut object_count = 0;

    println!("  Allocating objects until automatic GC is triggered...");

    for _i in 0..100 {
        // Try at most 100 times
        // Allocate objects of about 100 bytes
        let node = SimpleNode {
            _data: vec![0u8; 100],
        };
        match unsafe { context.alloc_raw(partition, node) } {
            Ok(_gc_ref) => {
                allocated_bytes += 100 + std::mem::size_of::<GcRef<SimpleNode>>(); // Estimated size
                object_count += 1;

                // Check if approaching threshold
                if let Some(partition_info) = context.partition(partition)
                    && partition_info.memory_used() >= 1500
                {
                    println!(
                        "  Reached automatic GC threshold, allocated {} objects",
                        object_count
                    );
                    println!("  Estimated allocated memory: {} bytes", allocated_bytes);
                    println!(
                        "  Actual memory usage: {} bytes",
                        partition_info.memory_used()
                    );
                    break;
                }
            }
            Err(_) => {
                println!("  Allocation failed, automatic GC may have been triggered");
                break;
            }
        }
    }

    // Manually trigger GC to see effect
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Manual GC freed {} bytes", freed);
}

pub fn should_gc(&self) -> bool

Check if garbage collection is needed

pub fn set_root_node(&mut self, node: NonNull<GcHead>)

pub fn contains(&self, node: NonNull<GcHead>) -> bool

Check if node was allocated in this heap

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 fn protect_node( &mut self, scope_stack_id: GcScopeStackId, node: NonNull<GcHead>, ) -> bool

Protect node from being gc collected.

1. if node is local or root, it’s protected, returns true
2. otherwise if has current scope, add node to current scope and returns true
3. can’t protect, returns false

pub fn protect_nodes_iter( &mut self, scope_stack_id: GcScopeStackId, nodes: impl Iterator<Item = NonNull<GcHead>>, )

Protect nodes from being gc collected, for each node do following steps:

1. if node is local or root, do nothing
2. if has current scope, add node to current scope
3. can’t protect, returns false

pub fn protect_nodes( &mut self, scope_stack_id: GcScopeStackId, nodes: &[NonNull<GcHead>], )

Protect nodes from being gc collected, for each node do following steps:

1. if node is local or root, do nothing
2. if has current scope, add node to current scope
3. can’t protect, returns false

pub const fn memory_used(&self) -> usize

impl GcHeap

pub fn add_gray_node(&mut self, node: NonNull<GcHead>)

pub fn mark_reset(&mut self, partition_id: GcPartitionId)

pub fn mark_prepare(&mut self, partition_id: GcPartitionId)

pub fn mark_grays( &mut self, partition_id: GcPartitionId, max_steps: usize, ) -> bool

pub fn mark(&mut self, partition_id: GcPartitionId, max_steps: usize) -> bool

pub fn sweep( &mut self, partition_id: GcPartitionId, on_dispose: impl Fn(&GcHeap, &GcHead), ) -> usize

dispose white nodes in the partition. on_dispose is called BEFORE a node will be disposed.

pub fn garbage_collect( &mut self, partition_id: GcPartitionId, on_dispose: impl Fn(&GcHeap, &GcHead), ) -> usize

Collect garbage on given partition, call notify with node BEFORE it is disposed.

Examples found in repository

examples/advanced_features.rs (line 103)

fn demonstrate_weak_references(
    heap: &mut GcHeap,
    partition: gc_lite::GcPartitionId,
) -> GcResult<()> {
    println!("1. Create strong and weak references...");

    let strong_ref =
        unsafe { heap.alloc_root_raw(partition, MyString(String::from("Strong Reference Data"))) }
            .map_err(|(err, _)| err)?;

    let weak_ref = heap.downgrade(&strong_ref);
    println!("  Created strong reference: {:?}", strong_ref);
    println!("  Created weak reference: {:?}", weak_ref);

    // Upgrade weak reference
    println!("\n2. Upgrade weak reference...");
    match weak_ref.upgrade(heap) {
        Some(upgraded) => {
            let data = &*upgraded;
            println!("  Weak reference upgrade successful: '{}'", data);
            assert_eq!(data, "Strong Reference Data");
        }
        None => println!("  Weak reference upgrade failed"),
    }

    // Try upgrading after releasing strong reference
    println!("\n3. Upgrade weak reference after releasing strong reference...");
    heap.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);

    match weak_ref.upgrade(heap) {
        Some(_) => {
            println!("  Weak reference can still be upgraded (object may still be in memory)")
        }
        None => println!("  Weak reference upgrade failed (object has been collected)"),
    }

    Ok(())
}

/// Demonstrate circular reference handling
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(())
}

examples/performance_benchmark.rs (line 72)

fn benchmark_object_sizes() {
    let sizes = [10, 100, 500, 1000, 5000];

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

        let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
        let partition = context.create_partition(64 * 1024, 16 * 1024);

        // Measure allocation performance
        let alloc_start = Instant::now();
        let mut objects = Vec::new();
        for _i in 0..size {
            let node = unsafe {
                context.alloc_raw(
                    partition,
                    SimpleNode {
                        _data: vec![0u8; 100],
                    },
                )
            } // Each node 100 bytes
            .unwrap();
            objects.push(node);
        }
        let alloc_duration = alloc_start.elapsed();

        println!("  Allocated {} objects in: {:?}", size, alloc_duration);
        println!(
            "  Average allocation time per object: {:?}",
            alloc_duration / size as u32
        );

        // Measure GC performance (all objects can be collected)
        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!(
            "  Average collection time per byte: {:?}",
            if freed > 0 {
                gc_duration / freed as u32
            } else {
                Duration::from_nanos(0)
            }
        );
    }
}

/// Test GC performance of complex object graphs
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 }
        );
    }
}

/// Test memory usage efficiency
fn benchmark_memory_efficiency() {
    println!("\nTesting memory usage efficiency...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024 * 1024); // 1MB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate many small objects
    let small_objects_count = 1000;
    let mut small_objects = Vec::new();

    for _i in 0..small_objects_count {
        let obj = unsafe { context.alloc_raw(partition, SmallData {}) }.unwrap();
        small_objects.push(obj);
    }

    if let Some(partition_info) = context.partition(partition) {
        let used = partition_info.memory_used();
        let limit = context.memory_limit();
        let efficiency = if limit > 0 {
            (used as f64 / limit as f64) * 100.0
        } else {
            0.0
        };

        println!("  After allocating {} small objects:", small_objects_count);
        println!(
            "  Memory usage: {}/{} bytes ({:.1}%)",
            used, limit, efficiency
        );
        println!(
            "  Average overhead per object: {} bytes",
            if small_objects_count > 0 {
                used / small_objects_count
            } else {
                0
            }
        );
    }

    // Collect all objects
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected all objects, freed {} bytes", freed);

    // Verify complete memory collection
    if let Some(partition_info) = context.partition(partition) {
        let used_after = partition_info.memory_used();
        println!("  Memory usage after collection: {} bytes", used_after);
        println!(
            "  Memory collection rate: {:.1}%",
            if freed > 0 {
                (freed as f64 / (freed + used_after) as f64) * 100.0
            } else {
                0.0
            }
        );
    }
}

/// Test automatic GC threshold performance
fn benchmark_auto_gc_threshold() {
    println!("\nTesting automatic GC threshold performance...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Set automatic GC threshold to 1.5KB
    context.set_gc_threshold(1500);

    // Allocate objects until automatic GC is triggered
    let mut allocated_bytes = 0;
    let mut object_count = 0;

    println!("  Allocating objects until automatic GC is triggered...");

    for _i in 0..100 {
        // Try at most 100 times
        // Allocate objects of about 100 bytes
        let node = SimpleNode {
            _data: vec![0u8; 100],
        };
        match unsafe { context.alloc_raw(partition, node) } {
            Ok(_gc_ref) => {
                allocated_bytes += 100 + std::mem::size_of::<GcRef<SimpleNode>>(); // Estimated size
                object_count += 1;

                // Check if approaching threshold
                if let Some(partition_info) = context.partition(partition)
                    && partition_info.memory_used() >= 1500
                {
                    println!(
                        "  Reached automatic GC threshold, allocated {} objects",
                        object_count
                    );
                    println!("  Estimated allocated memory: {} bytes", allocated_bytes);
                    println!(
                        "  Actual memory usage: {} bytes",
                        partition_info.memory_used()
                    );
                    break;
                }
            }
            Err(_) => {
                println!("  Allocation failed, automatic GC may have been triggered");
                break;
            }
        }
    }

    // Manually trigger GC to see effect
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Manual GC freed {} bytes", freed);
}

examples/error_handling.rs (line 76)

fn demonstrate_out_of_memory() -> GcResult<()> {
    println!("1. Create limited memory partition...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate first large object (1KB + header)
    println!("2. Allocate first large object...");
    let gc1: GcRef<LargeData> =
        match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
            Ok(gc_ref) => {
                println!("  ✓ Successfully allocated first object (1KB)");
                gc_ref
            }
            Err((error, _)) => {
                println!("  ✗ First object allocation failed: {:?}", error);
                return Ok(());
            }
        };

    // Allocate second large object (1KB + header) - should exceed 2KB limit
    println!("3. Try to allocate second large object...");
    match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
        Err((GcError::PartitionFull, _)) => {
            println!("  ✓ Correctly detected partition full error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition full error, but allocation succeeded");
            return Ok(());
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition full error, but got: {:?}",
                other_error
            );
            return Ok(());
        }
    }

    // Clean up - through garbage collection instead of manual release
    println!("  ✓ Automatic cleanup through GC");
    context.garbage_collect(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);

    Ok(())
}

examples/basic_usage.rs (line 120)

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

impl GcHeap

pub unsafe fn alloc_raw<T: GcNode>( &mut self, partition_id: GcPartitionId, payload: T, ) -> Result<GcRef<T>, (GcError, T)>

Allocate a typed gc node with payload data, do not put to any scope, even if the current scope is present.

SAFETY

This function is unsafe because it directly manipulates raw pointers and memory allocation. The caller must ensure that the partition_id is valid and that the returned GcRef is properly managed to avoid memory leaks or use-after-free errors.

Examples found in repository

examples/performance_benchmark.rs (lines 52-57)

fn benchmark_object_sizes() {
    let sizes = [10, 100, 500, 1000, 5000];

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

        let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
        let partition = context.create_partition(64 * 1024, 16 * 1024);

        // Measure allocation performance
        let alloc_start = Instant::now();
        let mut objects = Vec::new();
        for _i in 0..size {
            let node = unsafe {
                context.alloc_raw(
                    partition,
                    SimpleNode {
                        _data: vec![0u8; 100],
                    },
                )
            } // Each node 100 bytes
            .unwrap();
            objects.push(node);
        }
        let alloc_duration = alloc_start.elapsed();

        println!("  Allocated {} objects in: {:?}", size, alloc_duration);
        println!(
            "  Average allocation time per object: {:?}",
            alloc_duration / size as u32
        );

        // Measure GC performance (all objects can be collected)
        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!(
            "  Average collection time per byte: {:?}",
            if freed > 0 {
                gc_duration / freed as u32
            } else {
                Duration::from_nanos(0)
            }
        );
    }
}

/// Test GC performance of complex object graphs
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 }
        );
    }
}

/// Test memory usage efficiency
fn benchmark_memory_efficiency() {
    println!("\nTesting memory usage efficiency...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024 * 1024); // 1MB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate many small objects
    let small_objects_count = 1000;
    let mut small_objects = Vec::new();

    for _i in 0..small_objects_count {
        let obj = unsafe { context.alloc_raw(partition, SmallData {}) }.unwrap();
        small_objects.push(obj);
    }

    if let Some(partition_info) = context.partition(partition) {
        let used = partition_info.memory_used();
        let limit = context.memory_limit();
        let efficiency = if limit > 0 {
            (used as f64 / limit as f64) * 100.0
        } else {
            0.0
        };

        println!("  After allocating {} small objects:", small_objects_count);
        println!(
            "  Memory usage: {}/{} bytes ({:.1}%)",
            used, limit, efficiency
        );
        println!(
            "  Average overhead per object: {} bytes",
            if small_objects_count > 0 {
                used / small_objects_count
            } else {
                0
            }
        );
    }

    // Collect all objects
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected all objects, freed {} bytes", freed);

    // Verify complete memory collection
    if let Some(partition_info) = context.partition(partition) {
        let used_after = partition_info.memory_used();
        println!("  Memory usage after collection: {} bytes", used_after);
        println!(
            "  Memory collection rate: {:.1}%",
            if freed > 0 {
                (freed as f64 / (freed + used_after) as f64) * 100.0
            } else {
                0.0
            }
        );
    }
}

/// Test automatic GC threshold performance
fn benchmark_auto_gc_threshold() {
    println!("\nTesting automatic GC threshold performance...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Set automatic GC threshold to 1.5KB
    context.set_gc_threshold(1500);

    // Allocate objects until automatic GC is triggered
    let mut allocated_bytes = 0;
    let mut object_count = 0;

    println!("  Allocating objects until automatic GC is triggered...");

    for _i in 0..100 {
        // Try at most 100 times
        // Allocate objects of about 100 bytes
        let node = SimpleNode {
            _data: vec![0u8; 100],
        };
        match unsafe { context.alloc_raw(partition, node) } {
            Ok(_gc_ref) => {
                allocated_bytes += 100 + std::mem::size_of::<GcRef<SimpleNode>>(); // Estimated size
                object_count += 1;

                // Check if approaching threshold
                if let Some(partition_info) = context.partition(partition)
                    && partition_info.memory_used() >= 1500
                {
                    println!(
                        "  Reached automatic GC threshold, allocated {} objects",
                        object_count
                    );
                    println!("  Estimated allocated memory: {} bytes", allocated_bytes);
                    println!(
                        "  Actual memory usage: {} bytes",
                        partition_info.memory_used()
                    );
                    break;
                }
            }
            Err(_) => {
                println!("  Allocation failed, automatic GC may have been triggered");
                break;
            }
        }
    }

    // Manually trigger GC to see effect
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Manual GC freed {} bytes", freed);
}

examples/error_handling.rs (line 44)

fn demonstrate_out_of_memory() -> GcResult<()> {
    println!("1. Create limited memory partition...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate first large object (1KB + header)
    println!("2. Allocate first large object...");
    let gc1: GcRef<LargeData> =
        match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
            Ok(gc_ref) => {
                println!("  ✓ Successfully allocated first object (1KB)");
                gc_ref
            }
            Err((error, _)) => {
                println!("  ✗ First object allocation failed: {:?}", error);
                return Ok(());
            }
        };

    // Allocate second large object (1KB + header) - should exceed 2KB limit
    println!("3. Try to allocate second large object...");
    match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
        Err((GcError::PartitionFull, _)) => {
            println!("  ✓ Correctly detected partition full error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition full error, but allocation succeeded");
            return Ok(());
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition full error, but got: {:?}",
                other_error
            );
            return Ok(());
        }
    }

    // Clean up - through garbage collection instead of manual release
    println!("  ✓ Automatic cleanup through GC");
    context.garbage_collect(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);

    Ok(())
}

/// Demonstrate partition management errors
fn demonstrate_partition_management_errors() -> GcResult<()> {
    println!("1. Test non-existent partition operations...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    let invalid_partition = gc_lite::GcPartitionId(9999); // Non-existent partition

    // Test allocating objects in non-existent partition
    match unsafe {
        context.alloc_raw(
            invalid_partition,
            TestData {
                value: 42,
                name: "test".to_string(),
            },
        )
    } {
        Err((GcError::PartitionNotFound, _)) => {
            println!("  ✓ Allocating objects in non-existent partition returns correct error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition not found error, but allocation succeeded");
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition not found error, but got: {:?}",
                other_error
            );
        }
    }

    // Test getting non-existent partition information
    let partition_info = context.partition(invalid_partition);
    assert!(
        partition_info.is_none(),
        "Non-existent partition should return None"
    );
    println!("  ✓ Getting non-existent partition info returns None");

    // Test removing non-existent partition (remove_partition doesn't return error, just silently fails)
    context.remove_partition(invalid_partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Removing non-existent partition silently fails");

    println!("\n2. Test non-empty partition deletion...");
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate objects in partition
    let obj = unsafe {
        context.alloc_raw(
            partition_id,
            TestData {
                value: 1,
                name: "obj".to_string(),
            },
        )
    }
    .unwrap();
    let _ = obj;

    // Try to delete non-empty partition (remove_partition will force cleanup)
    context.remove_partition(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Successfully deleted non-empty partition (root objects were force cleaned)");

    Ok(())
}

examples/advanced_features.rs (line 179)

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

examples/basic_usage.rs (line 66)

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 alloc_root_raw<T: GcNode>( &mut self, partition_id: GcPartitionId, payload: T, ) -> Result<GcRef<T>, (GcError, T)>

Allocate a root node — bypasses arena directly to system malloc.

Root nodes are permanent and should not waste arena space.

SAFETY

This function is unsafe because it directly manipulates raw pointers and memory allocation. The caller must ensure that the partition_id is valid and that the returned GcRef is properly managed to avoid memory leaks or use-after-free errors.

Examples found in repository

examples/advanced_features.rs (line 83)

fn demonstrate_weak_references(
    heap: &mut GcHeap,
    partition: gc_lite::GcPartitionId,
) -> GcResult<()> {
    println!("1. Create strong and weak references...");

    let strong_ref =
        unsafe { heap.alloc_root_raw(partition, MyString(String::from("Strong Reference Data"))) }
            .map_err(|(err, _)| err)?;

    let weak_ref = heap.downgrade(&strong_ref);
    println!("  Created strong reference: {:?}", strong_ref);
    println!("  Created weak reference: {:?}", weak_ref);

    // Upgrade weak reference
    println!("\n2. Upgrade weak reference...");
    match weak_ref.upgrade(heap) {
        Some(upgraded) => {
            let data = &*upgraded;
            println!("  Weak reference upgrade successful: '{}'", data);
            assert_eq!(data, "Strong Reference Data");
        }
        None => println!("  Weak reference upgrade failed"),
    }

    // Try upgrading after releasing strong reference
    println!("\n3. Upgrade weak reference after releasing strong reference...");
    heap.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);

    match weak_ref.upgrade(heap) {
        Some(_) => {
            println!("  Weak reference can still be upgraded (object may still be in memory)")
        }
        None => println!("  Weak reference upgrade failed (object has been collected)"),
    }

    Ok(())
}

/// Demonstrate circular reference handling
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(())
}

impl GcHeap

pub fn bind(&mut self, master: NonNull<GcHead>, slave: NonNull<GcHead>)

Establishes a directed reference from master to slave and performs the necessary write barrier for tri-color incremental GC.

When to use

Call this whenever a GC node (master) starts referencing another GC node (slave) through a pointer write, e.g.:

• Setting an object property to an object/string value
• Pushing an element into an array
• Storing a result value into a Promise
• Updating a closure variable reference

Write barrier semantics

In tri-color marking, if master is already Black (fully traced) and slave is White (not yet traced), the slave would be incorrectly swept as garbage. This method prevents that by:

1. Checking the colors of master and slave.
2. If master is Black and slave is White/Gray, marking slave as Gray and enqueuing it into the gray list of its partition, ensuring it will be traced in the current GC cycle.

Safety

Both pointers must point to valid, live GC nodes managed by this heap.

impl GcHeap

pub fn nodes(&self, partition_id: GcPartitionId) -> NodeLinkIter<'_>

impl GcHeap

pub fn create_partition( &mut self, arena_capacity: usize, arena_max_alloc: usize, ) -> GcPartitionId

Create a new partition and return its ID.

Parameters

• arena_capacity: arena size in bytes. 0 = disable arena for this partition.
• arena_max_alloc: allocations larger than this skip the arena.

Examples found in repository

examples/gc_node_usage.rs (line 58)

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 49)

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

    let mut heap = new_heap();
    let partition = heap.create_partition(64 * 1024, 16 * 1024);

    // Demonstrate weak reference functionality
    println!("\n=== Weak reference functionality demonstration ===");
    demonstrate_weak_references(&mut heap, partition)?;

    // Demonstrate circular reference handling
    println!("\n=== Circular reference handling demonstration ===");
    demonstrate_cyclic_references(&mut heap, partition)?;

    // Demonstrate complex data structures
    println!("\n=== Complex data structures demonstration ===");
    demonstrate_complex_structures(&mut heap, partition)?;

    // Demonstrate reference recovery functionality
    println!("\n=== Reference recovery functionality demonstration ===");
    demonstrate_reference_recovery(&mut heap, partition)?;

    // Demonstrate cross-context detection
    println!("\n=== Cross-context detection demonstration ===");
    demonstrate_cross_context_detection()?;

    println!("\nAll advanced feature demonstrations completed!");
    Ok(())
}

/// Demonstrate weak reference functionality
fn demonstrate_weak_references(
    heap: &mut GcHeap,
    partition: gc_lite::GcPartitionId,
) -> GcResult<()> {
    println!("1. Create strong and weak references...");

    let strong_ref =
        unsafe { heap.alloc_root_raw(partition, MyString(String::from("Strong Reference Data"))) }
            .map_err(|(err, _)| err)?;

    let weak_ref = heap.downgrade(&strong_ref);
    println!("  Created strong reference: {:?}", strong_ref);
    println!("  Created weak reference: {:?}", weak_ref);

    // Upgrade weak reference
    println!("\n2. Upgrade weak reference...");
    match weak_ref.upgrade(heap) {
        Some(upgraded) => {
            let data = &*upgraded;
            println!("  Weak reference upgrade successful: '{}'", data);
            assert_eq!(data, "Strong Reference Data");
        }
        None => println!("  Weak reference upgrade failed"),
    }

    // Try upgrading after releasing strong reference
    println!("\n3. Upgrade weak reference after releasing strong reference...");
    heap.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);

    match weak_ref.upgrade(heap) {
        Some(_) => {
            println!("  Weak reference can still be upgraded (object may still be in memory)")
        }
        None => println!("  Weak reference upgrade failed (object has been collected)"),
    }

    Ok(())
}

/// Demonstrate circular reference handling
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(())
}

examples/performance_benchmark.rs (line 45)

fn benchmark_object_sizes() {
    let sizes = [10, 100, 500, 1000, 5000];

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

        let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
        let partition = context.create_partition(64 * 1024, 16 * 1024);

        // Measure allocation performance
        let alloc_start = Instant::now();
        let mut objects = Vec::new();
        for _i in 0..size {
            let node = unsafe {
                context.alloc_raw(
                    partition,
                    SimpleNode {
                        _data: vec![0u8; 100],
                    },
                )
            } // Each node 100 bytes
            .unwrap();
            objects.push(node);
        }
        let alloc_duration = alloc_start.elapsed();

        println!("  Allocated {} objects in: {:?}", size, alloc_duration);
        println!(
            "  Average allocation time per object: {:?}",
            alloc_duration / size as u32
        );

        // Measure GC performance (all objects can be collected)
        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!(
            "  Average collection time per byte: {:?}",
            if freed > 0 {
                gc_duration / freed as u32
            } else {
                Duration::from_nanos(0)
            }
        );
    }
}

/// Test GC performance of complex object graphs
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 }
        );
    }
}

/// Test memory usage efficiency
fn benchmark_memory_efficiency() {
    println!("\nTesting memory usage efficiency...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024 * 1024); // 1MB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate many small objects
    let small_objects_count = 1000;
    let mut small_objects = Vec::new();

    for _i in 0..small_objects_count {
        let obj = unsafe { context.alloc_raw(partition, SmallData {}) }.unwrap();
        small_objects.push(obj);
    }

    if let Some(partition_info) = context.partition(partition) {
        let used = partition_info.memory_used();
        let limit = context.memory_limit();
        let efficiency = if limit > 0 {
            (used as f64 / limit as f64) * 100.0
        } else {
            0.0
        };

        println!("  After allocating {} small objects:", small_objects_count);
        println!(
            "  Memory usage: {}/{} bytes ({:.1}%)",
            used, limit, efficiency
        );
        println!(
            "  Average overhead per object: {} bytes",
            if small_objects_count > 0 {
                used / small_objects_count
            } else {
                0
            }
        );
    }

    // Collect all objects
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected all objects, freed {} bytes", freed);

    // Verify complete memory collection
    if let Some(partition_info) = context.partition(partition) {
        let used_after = partition_info.memory_used();
        println!("  Memory usage after collection: {} bytes", used_after);
        println!(
            "  Memory collection rate: {:.1}%",
            if freed > 0 {
                (freed as f64 / (freed + used_after) as f64) * 100.0
            } else {
                0.0
            }
        );
    }
}

/// Test automatic GC threshold performance
fn benchmark_auto_gc_threshold() {
    println!("\nTesting automatic GC threshold performance...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Set automatic GC threshold to 1.5KB
    context.set_gc_threshold(1500);

    // Allocate objects until automatic GC is triggered
    let mut allocated_bytes = 0;
    let mut object_count = 0;

    println!("  Allocating objects until automatic GC is triggered...");

    for _i in 0..100 {
        // Try at most 100 times
        // Allocate objects of about 100 bytes
        let node = SimpleNode {
            _data: vec![0u8; 100],
        };
        match unsafe { context.alloc_raw(partition, node) } {
            Ok(_gc_ref) => {
                allocated_bytes += 100 + std::mem::size_of::<GcRef<SimpleNode>>(); // Estimated size
                object_count += 1;

                // Check if approaching threshold
                if let Some(partition_info) = context.partition(partition)
                    && partition_info.memory_used() >= 1500
                {
                    println!(
                        "  Reached automatic GC threshold, allocated {} objects",
                        object_count
                    );
                    println!("  Estimated allocated memory: {} bytes", allocated_bytes);
                    println!(
                        "  Actual memory usage: {} bytes",
                        partition_info.memory_used()
                    );
                    break;
                }
            }
            Err(_) => {
                println!("  Allocation failed, automatic GC may have been triggered");
                break;
            }
        }
    }

    // Manually trigger GC to see effect
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Manual GC freed {} bytes", freed);
}

examples/error_handling.rs (line 39)

fn demonstrate_out_of_memory() -> GcResult<()> {
    println!("1. Create limited memory partition...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate first large object (1KB + header)
    println!("2. Allocate first large object...");
    let gc1: GcRef<LargeData> =
        match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
            Ok(gc_ref) => {
                println!("  ✓ Successfully allocated first object (1KB)");
                gc_ref
            }
            Err((error, _)) => {
                println!("  ✗ First object allocation failed: {:?}", error);
                return Ok(());
            }
        };

    // Allocate second large object (1KB + header) - should exceed 2KB limit
    println!("3. Try to allocate second large object...");
    match unsafe { context.alloc_raw(partition_id, LargeData { data: [0; 1024] }) } {
        Err((GcError::PartitionFull, _)) => {
            println!("  ✓ Correctly detected partition full error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition full error, but allocation succeeded");
            return Ok(());
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition full error, but got: {:?}",
                other_error
            );
            return Ok(());
        }
    }

    // Clean up - through garbage collection instead of manual release
    println!("  ✓ Automatic cleanup through GC");
    context.garbage_collect(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);

    Ok(())
}

/// Demonstrate partition management errors
fn demonstrate_partition_management_errors() -> GcResult<()> {
    println!("1. Test non-existent partition operations...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    let invalid_partition = gc_lite::GcPartitionId(9999); // Non-existent partition

    // Test allocating objects in non-existent partition
    match unsafe {
        context.alloc_raw(
            invalid_partition,
            TestData {
                value: 42,
                name: "test".to_string(),
            },
        )
    } {
        Err((GcError::PartitionNotFound, _)) => {
            println!("  ✓ Allocating objects in non-existent partition returns correct error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition not found error, but allocation succeeded");
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition not found error, but got: {:?}",
                other_error
            );
        }
    }

    // Test getting non-existent partition information
    let partition_info = context.partition(invalid_partition);
    assert!(
        partition_info.is_none(),
        "Non-existent partition should return None"
    );
    println!("  ✓ Getting non-existent partition info returns None");

    // Test removing non-existent partition (remove_partition doesn't return error, just silently fails)
    context.remove_partition(invalid_partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Removing non-existent partition silently fails");

    println!("\n2. Test non-empty partition deletion...");
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate objects in partition
    let obj = unsafe {
        context.alloc_raw(
            partition_id,
            TestData {
                value: 1,
                name: "obj".to_string(),
            },
        )
    }
    .unwrap();
    let _ = obj;

    // Try to delete non-empty partition (remove_partition will force cleanup)
    context.remove_partition(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Successfully deleted non-empty partition (root objects were force cleaned)");

    Ok(())
}

/// Demonstrate GC threshold API errors
fn demonstrate_gc_threshold_errors() -> GcResult<()> {
    println!("1. Test GC threshold API...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024);
    let _partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Test default values
    println!("2. Test default threshold...");
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Default threshold is 0, automatic GC disabled");

    // Test setting threshold
    println!("3. Test setting threshold...");
    context.set_gc_threshold(512);
    assert_eq!(context.gc_threshold(), 512);
    println!("  ✓ Successfully set threshold to 512, automatic GC enabled");

    // Test setting threshold exceeding memory limit
    println!("4. Test setting threshold exceeding memory limit...");
    context.set_gc_threshold(2048);
    // Since threshold exceeds memory limit, will be capped at 0.8x of limit (1024 * 8 / 10 = 819)
    assert_eq!(context.gc_threshold(), 819);
    println!(
        "  ✓ Setting threshold exceeding memory limit automatically adjusted to 0.8x of memory limit"
    );

    // Test disabling automatic GC
    println!("5. Test disabling automatic GC...");
    context.set_gc_threshold(0);
    assert_eq!(context.gc_threshold(), 0);
    println!("  ✓ Successfully disabled automatic GC, threshold set to 0");

    Ok(())
}

examples/basic_usage.rs (line 58)

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 fn finalize_partition( &self, partition_id: GcPartitionId, ) -> Option<GcNodeLink>

Phase 1: Finalize — call Drop on all node payloads without freeing memory.

Only takes &self, so Drop implementations can safely access GcHeap via a shared reference. Returns the node link containing all finalized nodes, which must be passed to [dealloc_partition] to reclaim memory.

Scope caches associated with this partition are cleared before any drops are called, so that GcScopeState::clear() (which only touches node flags) runs before payload drops.

pub fn dealloc_partition( &mut self, partition_id: GcPartitionId, link: GcNodeLink, ) -> usize

Phase 2: Dealloc — free memory of all finalized nodes and reset the partition.

Takes &mut self — no Drop callbacks run at this point, so there is no risk of reentrant &mut self access. The link must be the value returned by [finalize_partition] for the same partition.

Returns the total number of bytes freed.

pub fn remove_partition( &mut self, partition_id: GcPartitionId, _on_dispose: impl Fn(&GcHeap, &GcHead), ) -> usize

👎Deprecated:

unsound — use finalize_partition(&self) + dealloc_partition(&mut self) instead

Remove a partition and reclaim all its memory.

⚠️ DEPRECATED — This method is inherently unsound. It holds &mut self while Drop callbacks run inside [finalize_partition], and those callbacks can re-enter GcHeap through raw pointers, creating aliasing &mut references (UB).

Use the two-phase API instead:

let link = gc_heap.finalize_partition(pid);
// ... (Drop callbacks that access GcHeap are safe here) ...
if let Some(link) = link {
    gc_heap.dealloc_partition(pid, link);
}

See [finalize_partition] (takes &self) and [dealloc_partition] (takes &mut self) for details.

The on_dispose parameter is kept for API compatibility but is no longer called — Drop is handled internally by finalize_partition.

Examples found in repository

examples/error_handling.rs (line 121)

fn demonstrate_partition_management_errors() -> GcResult<()> {
    println!("1. Test non-existent partition operations...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    let invalid_partition = gc_lite::GcPartitionId(9999); // Non-existent partition

    // Test allocating objects in non-existent partition
    match unsafe {
        context.alloc_raw(
            invalid_partition,
            TestData {
                value: 42,
                name: "test".to_string(),
            },
        )
    } {
        Err((GcError::PartitionNotFound, _)) => {
            println!("  ✓ Allocating objects in non-existent partition returns correct error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition not found error, but allocation succeeded");
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition not found error, but got: {:?}",
                other_error
            );
        }
    }

    // Test getting non-existent partition information
    let partition_info = context.partition(invalid_partition);
    assert!(
        partition_info.is_none(),
        "Non-existent partition should return None"
    );
    println!("  ✓ Getting non-existent partition info returns None");

    // Test removing non-existent partition (remove_partition doesn't return error, just silently fails)
    context.remove_partition(invalid_partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Removing non-existent partition silently fails");

    println!("\n2. Test non-empty partition deletion...");
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate objects in partition
    let obj = unsafe {
        context.alloc_raw(
            partition_id,
            TestData {
                value: 1,
                name: "obj".to_string(),
            },
        )
    }
    .unwrap();
    let _ = obj;

    // Try to delete non-empty partition (remove_partition will force cleanup)
    context.remove_partition(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Successfully deleted non-empty partition (root objects were force cleaned)");

    Ok(())
}

examples/basic_usage.rs (line 211)

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 fn partition(&self, partition_id: GcPartitionId) -> Option<&GcPartition>

Get partition information

Examples found in repository

examples/performance_benchmark.rs (line 172)

fn benchmark_memory_efficiency() {
    println!("\nTesting memory usage efficiency...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(1024 * 1024); // 1MB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate many small objects
    let small_objects_count = 1000;
    let mut small_objects = Vec::new();

    for _i in 0..small_objects_count {
        let obj = unsafe { context.alloc_raw(partition, SmallData {}) }.unwrap();
        small_objects.push(obj);
    }

    if let Some(partition_info) = context.partition(partition) {
        let used = partition_info.memory_used();
        let limit = context.memory_limit();
        let efficiency = if limit > 0 {
            (used as f64 / limit as f64) * 100.0
        } else {
            0.0
        };

        println!("  After allocating {} small objects:", small_objects_count);
        println!(
            "  Memory usage: {}/{} bytes ({:.1}%)",
            used, limit, efficiency
        );
        println!(
            "  Average overhead per object: {} bytes",
            if small_objects_count > 0 {
                used / small_objects_count
            } else {
                0
            }
        );
    }

    // Collect all objects
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Collected all objects, freed {} bytes", freed);

    // Verify complete memory collection
    if let Some(partition_info) = context.partition(partition) {
        let used_after = partition_info.memory_used();
        println!("  Memory usage after collection: {} bytes", used_after);
        println!(
            "  Memory collection rate: {:.1}%",
            if freed > 0 {
                (freed as f64 / (freed + used_after) as f64) * 100.0
            } else {
                0.0
            }
        );
    }
}

/// Test automatic GC threshold performance
fn benchmark_auto_gc_threshold() {
    println!("\nTesting automatic GC threshold performance...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    context.set_memory_limit(2048); // 2KB global limit
    let partition = context.create_partition(64 * 1024, 16 * 1024);

    // Set automatic GC threshold to 1.5KB
    context.set_gc_threshold(1500);

    // Allocate objects until automatic GC is triggered
    let mut allocated_bytes = 0;
    let mut object_count = 0;

    println!("  Allocating objects until automatic GC is triggered...");

    for _i in 0..100 {
        // Try at most 100 times
        // Allocate objects of about 100 bytes
        let node = SimpleNode {
            _data: vec![0u8; 100],
        };
        match unsafe { context.alloc_raw(partition, node) } {
            Ok(_gc_ref) => {
                allocated_bytes += 100 + std::mem::size_of::<GcRef<SimpleNode>>(); // Estimated size
                object_count += 1;

                // Check if approaching threshold
                if let Some(partition_info) = context.partition(partition)
                    && partition_info.memory_used() >= 1500
                {
                    println!(
                        "  Reached automatic GC threshold, allocated {} objects",
                        object_count
                    );
                    println!("  Estimated allocated memory: {} bytes", allocated_bytes);
                    println!(
                        "  Actual memory usage: {} bytes",
                        partition_info.memory_used()
                    );
                    break;
                }
            }
            Err(_) => {
                println!("  Allocation failed, automatic GC may have been triggered");
                break;
            }
        }
    }

    // Manually trigger GC to see effect
    let freed = context.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  Manual GC freed {} bytes", freed);
}

examples/error_handling.rs (line 113)

fn demonstrate_partition_management_errors() -> GcResult<()> {
    println!("1. Test non-existent partition operations...");

    let mut context = GcHeap::new(&GC_TYPE_REGISTRY);
    let invalid_partition = gc_lite::GcPartitionId(9999); // Non-existent partition

    // Test allocating objects in non-existent partition
    match unsafe {
        context.alloc_raw(
            invalid_partition,
            TestData {
                value: 42,
                name: "test".to_string(),
            },
        )
    } {
        Err((GcError::PartitionNotFound, _)) => {
            println!("  ✓ Allocating objects in non-existent partition returns correct error");
        }
        Ok(_) => {
            println!("  ✗ Expected partition not found error, but allocation succeeded");
        }
        Err((other_error, _)) => {
            println!(
                "  ✗ Expected partition not found error, but got: {:?}",
                other_error
            );
        }
    }

    // Test getting non-existent partition information
    let partition_info = context.partition(invalid_partition);
    assert!(
        partition_info.is_none(),
        "Non-existent partition should return None"
    );
    println!("  ✓ Getting non-existent partition info returns None");

    // Test removing non-existent partition (remove_partition doesn't return error, just silently fails)
    context.remove_partition(invalid_partition, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Removing non-existent partition silently fails");

    println!("\n2. Test non-empty partition deletion...");
    let partition_id = context.create_partition(64 * 1024, 16 * 1024);

    // Allocate objects in partition
    let obj = unsafe {
        context.alloc_raw(
            partition_id,
            TestData {
                value: 1,
                name: "obj".to_string(),
            },
        )
    }
    .unwrap();
    let _ = obj;

    // Try to delete non-empty partition (remove_partition will force cleanup)
    context.remove_partition(partition_id, GcHeap::DUMMY_DISPOSE_CALLBACK);
    println!("  ✓ Successfully deleted non-empty partition (root objects were force cleaned)");

    Ok(())
}

examples/basic_usage.rs (line 88)

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 fn partition_mut( &mut self, partition_id: GcPartitionId, ) -> Option<&mut GcPartition>

Get partition information

pub fn partition_ids(&self) -> Vec<GcPartitionId>

Get all partition IDs

Examples found in repository

examples/basic_usage.rs (line 54)

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

impl GcHeap

pub fn acquire_scope_stack(&mut self, par: GcPartitionId) -> GcScopeStackId

find an idle scope stack, or create a new if none available

Examples found in repository

examples/gc_node_usage.rs (line 59)

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

pub fn release_scope_stack(&mut self, stack_id: GcScopeStackId)

Examples found in repository

examples/gc_node_usage.rs (line 70)

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

pub fn scope_max_depth(&self, stack_id: GcScopeStackId) -> u32

get max depth of a scope stack

pub fn scope( &self, stack_id: GcScopeStackId, depth: u32, ) -> Option<&GcScopeState<'_>>

get scope state specified by (stack_id, depth). where depth is 1-based (1 means index #0)

pub unsafe fn scope_unchecked( &self, stack_id: GcScopeStackId, index: u32, ) -> &GcScopeState<'_>

Get scope state by 0-based index without bounds check.

Safety

Caller must ensure index < scope_max_depth(stack_id).

pub fn new_scope<'s>(&'s mut self, stack_id: GcScopeStackId) -> GcScope<'s>

push a new scope on the stack, returns new scope’s handle. the scope will be automatically popped when this handle is dropped.

Panics

Panics if an earlier handle is dropped while a later handle is still alive (LIFO order violation is enforced at runtime).

pub fn current_scope( &self, stack_id: GcScopeStackId, ) -> Option<&GcScopeState<'_>>

get last (top-most) scope from the stack

pub fn with_current_scope_of<R>( &mut self, stack_id: GcScopeStackId, f: impl FnOnce(&mut GcScopeState<'_>) -> R, ) -> Option<R>

run closure with last (top-most) scope from the stack

pub fn with_new_scope<R>( &mut self, stack_id: GcScopeStackId, f: impl FnOnce(GcScope<'_>) -> R, ) -> R

Examples found in repository

examples/gc_node_usage.rs (lines 31-38)

fn alloc_static(
    heap: &mut GcHeap,
    stack_id: GcScopeStackId,
    value: i32,
) -> GcResult<GcRef<StaticNode>> {
    heap.with_new_scope(stack_id, |ctx| {
        let r = ctx
            .alloc_local(StaticNode { _value: value })
            .map_err(|(err, _)| err)
            .map(|gc| gc.into_raw());
        ctx.clear();
        r
    })
}

fn alloc_other(
    heap: &mut GcHeap,
    stack_id: GcScopeStackId,
    value: i32,
) -> GcResult<GcRef<OtherNode>> {
    heap.with_new_scope(stack_id, |ctx| {
        let r = ctx
            .alloc_local(OtherNode { _value: value })
            .map_err(|(err, _)| err)
            .map(|gc| gc.into_raw());
        ctx.clear();
        r
    })
}

impl GcHeap

pub fn create_trace_ctx(&self, cap: usize) -> GcTraceCtx<'_>

pub fn trace_node(&self, node: NonNull<GcHead>, gcx: &mut GcTraceCtx<'_>)

Trace direct children of a node into the given trace context

pub fn traverse_start(&mut self, partition_id: GcPartitionId)

pub fn traverse( &mut self, node: NonNull<GcHead>, filter: Option<GcPartitionId>, callback: impl FnMut(NonNull<GcHead>, Option<NonNull<GcHead>>), )

Traverses the node tree starting at node in depth-first order, invoking callback on each visited node with its optional parent. If filter is Some, only nodes in the specified partition are visited.

impl GcHeap

pub fn downgrade<T: GcNode>(&mut self, gc_ref: &GcRef<T>) -> GcWeak<T>

Create weak reference.

Examples found in repository

examples/advanced_features.rs (line 86)

fn demonstrate_weak_references(
    heap: &mut GcHeap,
    partition: gc_lite::GcPartitionId,
) -> GcResult<()> {
    println!("1. Create strong and weak references...");

    let strong_ref =
        unsafe { heap.alloc_root_raw(partition, MyString(String::from("Strong Reference Data"))) }
            .map_err(|(err, _)| err)?;

    let weak_ref = heap.downgrade(&strong_ref);
    println!("  Created strong reference: {:?}", strong_ref);
    println!("  Created weak reference: {:?}", weak_ref);

    // Upgrade weak reference
    println!("\n2. Upgrade weak reference...");
    match weak_ref.upgrade(heap) {
        Some(upgraded) => {
            let data = &*upgraded;
            println!("  Weak reference upgrade successful: '{}'", data);
            assert_eq!(data, "Strong Reference Data");
        }
        None => println!("  Weak reference upgrade failed"),
    }

    // Try upgrading after releasing strong reference
    println!("\n3. Upgrade weak reference after releasing strong reference...");
    heap.garbage_collect(partition, GcHeap::DUMMY_DISPOSE_CALLBACK);

    match weak_ref.upgrade(heap) {
        Some(_) => {
            println!("  Weak reference can still be upgraded (object may still be in memory)")
        }
        None => println!("  Weak reference upgrade failed (object has been collected)"),
    }

    Ok(())
}

examples/basic_usage.rs (line 165)

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 fn upgrade<'a, T: GcNode>( &'a self, weak_ref: &GcWeak<T>, ) -> Option<Gc<'a, T>>

Upgrade weak reference

Trait Implementations

impl Drop for GcHeap

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.