Crate mtb_entity_slab

Expand description

§MTB Entity Allocator and Utilities

Address-stable, internally mutable entity Slab allocator. Mainly solves the problem where Slab cannot allocate new elements while reading existing ones.

地址稳定、内部可变的实体 Slab 分块分配器. 主要解决 Slab 无法在读取元素的同时分配新元素的问题.

§Example 使用示例

use mtb_entity_slab::*;

#[derive(Debug, Clone, PartialEq, Eq)]
struct Inst {
    pub opcode: u32,
    pub operands: [u64; 4],
    pub heap_data: String,
}

impl Inst {
    fn new(opcode: u32) -> Self {
        Self {
            opcode,
            operands: [0; 4],
            heap_data: format!("InstData{}", opcode),
        }
    }
}

let alloc: EntityAlloc<Inst, AllocPolicy256> = EntityAlloc::with_capacity(1024);
let ptrs = {
    let mut v = Vec::new();
    for i in 0..1000 {
        let ptr = PtrID::allocate_from(&alloc, Inst::new(i));
        v.push(ptr);
    }
    v
};

let inst = ptrs[500].deref(&alloc);

// Allocates a new element while reading existing ones
// 在读取时分配新元素
let new_id = PtrID::allocate_from(&alloc, Inst::new(2000));
assert_eq!(inst.opcode, 500);
assert_eq!(new_id.deref(&alloc).opcode, 2000);

for &ptr in ptrs.iter() {
    let inst = ptr.deref(&alloc);
    let indexed_id = ptr.to_index(&alloc).unwrap();
    assert_eq!(inst.opcode as usize, indexed_id.get_order());
}

§Safety 安全性

This crate provides access to allocated elements via PtrID. PtrID contains a raw pointer, and most operations on PtrID are safe, but there is no ABA usage detection.

This crate is designed for Remusys-IR and is for learning purposes only. It does not guarantee safety in all scenarios. Please carefully assess the risks when using it in production environments.

本库通过 PtrID 提供对分配元素的访问. PtrID 内部包含裸指针, 对 PtrID 的大多数操作都是安全的, 但没有 ABA 使用检测.

本库为 Remusys-IR 设计, 仅为学习用途, 不保证在所有场景下的安全性. 在生产环境中使用时请谨慎评估风险.

Structs§

AllocPolicy128: Entity allocation policy for chunks of size 128.
AllocPolicy256: Entity allocation policy for chunks of size 256.
AllocPolicy512: Entity allocation policy for chunks of size 512.
AllocPolicy1024: Entity allocation policy for chunks of size 1024.
AllocPolicy2048: Entity allocation policy for chunks of size 2048.
AllocPolicy4096: Entity allocation policy for chunks of size 4096.
EntityAlloc: Entity slab allocator for entities of type E using allocation policy P.
EntityAllocConsumeIter: Consuming iterator over allocated entities in an EntityAlloc.
EntityAllocEditIter: Mutable iterator over allocated entities in an EntityAlloc.
EntityAllocReadIter: Immutable iterator over allocated entities in an EntityAlloc.
EntityList: Doubly-linked list view over entities stored in an EntityAlloc.
EntityListIter: Iterator over a range of nodes in an EntityList.
EntityListNodeHead: Lightweight head metadata stored on each list node.
EntityListRange: A partial-close range of an entity pointer list representing [start, end).
EntityRingList: Ring list (circular) view over entities stored in an EntityAlloc.
EntityRingListIter: Iterator for EntityRingList that visits each node once starting after the sentinel.
GenIndex: Generation + index combined identifier used by the allocator.
IndexedID: Index-backed ID storing a GenIndex (real index + generation).
PtrID: Pointer-backed ID referencing a Unit<E> inside an EntityAlloc.

Enums§

EntityAccessErr: Possible errors when accessing allocated entities.
EntityListError: Error kinds returned by EntityList operations.
SlicePtrErr: Errors that can occur when working with slice pointers.

Constants§

MTBLIB_PACKAGE_NAME: Required by MTBLib package tools. Do not modify.
MTBLIB_PACKAGE_VERSION: Required by MTBLib package tools. Do not modify.

Traits§

IAllocPolicy: Entity allocation policy trait.
IEntityAllocID: Trait implemented by concrete ID representations that can reference entities inside an EntityAlloc.
IEntityListNodeID: Trait required for an entity ID to be used as a node in EntityList.
IEntityRingListNodeID: An entity pointer list node that supports ring lists.
IPoliciedID: Trait for ID wrappers that carry an associated object type and allocation policy.

Type Aliases§

EntityAccessRes: Result type for entity access operations.
EntityListRes: Result type returned by list operations.
IDBoundAlloc: Alias for EntityAlloc specialized to the object and policy types of an ID.
SlicePtrRes: Result type for operations involving slice pointers.

Attribute Macros§

entity_id