Struct GcPartition 

pub struct GcPartition { /* private fields */ }

Implementations

impl GcPartition

pub fn nodes_mut(&mut self) -> NodeLinkIterMut<'_>

impl GcPartition

pub fn new(capacity: usize, max_alloc: usize) -> Self

Create a new partition.

Parameters

• capacity: arena size in bytes. 0 = disable arena for this partition (all allocations go through system malloc directly).
• max_alloc: allocations larger than this skip the arena. When capacity == 0 this is forced to 0.

pub fn memory_used(&self) -> usize

Examples found in repository

examples/performance_benchmark.rs (line 173)

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/basic_usage.rs (line 93)

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 is_marking(&self) -> bool

Trait Implementations

impl Debug for GcPartition

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

Formats the value using the given formatter.