mtb_entity_slab/
lib.rs

1//! # MTB Entity Allocator and Utilities
2//!
3//! Address-stable, internally mutable entity Slab allocator. Mainly solves the problem
4//! where `Slab` cannot allocate new elements while reading existing ones.
5//!
6//! 地址稳定、内部可变的实体 Slab 分块分配器. 主要解决 `Slab` 无法在读取元素的同时
7//! 分配新元素的问题.
8//!
9//! ## Example 使用示例
10//!
11//! ```
12//! use mtb_entity_slab::*;
13//!
14//! #[derive(Debug, Clone, PartialEq, Eq)]
15//! struct Inst {
16//!     pub opcode: u32,
17//!     pub operands: [u64; 4],
18//!     pub heap_data: String,
19//! }
20//!
21//! impl Inst {
22//!     fn new(opcode: u32) -> Self {
23//!         Self {
24//!             opcode,
25//!             operands: [0; 4],
26//!             heap_data: format!("InstData{}", opcode),
27//!         }
28//!     }
29//! }
30//!
31//! let alloc: EntityAlloc<Inst, AllocPolicy256> = EntityAlloc::with_capacity(1024);
32//! let ptrs = {
33//!     let mut v = Vec::new();
34//!     for i in 0..1000 {
35//!         let ptr = PtrID::allocate_from(&alloc, Inst::new(i));
36//!         v.push(ptr);
37//!     }
38//!     v
39//! };
40//!
41//! let inst = ptrs[500].deref(&alloc);
42//!
43//! // Allocates a new element while reading existing ones
44//! // 在读取时分配新元素
45//! let new_id = PtrID::allocate_from(&alloc, Inst::new(2000));
46//! assert_eq!(inst.opcode, 500);
47//! assert_eq!(new_id.deref(&alloc).opcode, 2000);
48//!
49//! for &ptr in ptrs.iter() {
50//!     let inst = ptr.deref(&alloc);
51//!     let indexed_id = ptr.to_index(&alloc).unwrap();
52//!     assert_eq!(inst.opcode as usize, indexed_id.get_order());
53//! }
54//! ```
55//!
56//! ## Safety 安全性
57//!
58//! This crate provides access to allocated elements via `PtrID`. `PtrID` contains a raw pointer,
59//! and most operations on `PtrID` are safe, but there is no ABA usage detection.
60//!
61//! This crate is designed for Remusys-IR and is for learning purposes only. It does not guarantee
62//! safety in all scenarios. Please carefully assess the risks when using it in production environments.
63//!
64//! 本库通过 `PtrID` 提供对分配元素的访问. `PtrID` 内部包含裸指针, 对 PtrID 的大多数操作都是安全的,
65//! 但没有 ABA 使用检测.
66//!
67//! 本库为 Remusys-IR 设计, 仅为学习用途, 不保证在所有场景下的安全性. 在生产环境中使用时请谨慎评估风险.
68#![warn(missing_docs)]
69
70mod alloc;
71mod bitalloc;
72mod chunk;
73mod container;
74mod gen_index;
75mod id;
76mod iter;
77mod policy;
78
79pub use crate::{
80    alloc::{EntityAccessErr, EntityAccessRes, EntityAlloc},
81    container::list::{
82        EntityList, EntityListError, EntityListIter, EntityListNodeHead, EntityListRange,
83        EntityListRes, EntityRingList, EntityRingListIter, IEntityListNodeID,
84        IEntityRingListNodeID,
85    },
86    gen_index::GenIndex,
87    id::{IDBoundAlloc, IEntityAllocID, IPoliciedID, IndexedID, PtrID},
88    iter::{EntityAllocConsumeIter, EntityAllocEditIter, EntityAllocReadIter},
89    policy::{
90        AllocPolicy128, AllocPolicy256, AllocPolicy512, AllocPolicy1024, AllocPolicy2048,
91        AllocPolicy4096, IAllocPolicy, SlicePtrErr, SlicePtrRes,
92    },
93};
94pub use mtb_entity_slab_macros::entity_id;
95
96/// > Required by MTBLib package tools. Do not modify.
97///
98/// MTBLib package name.
99pub const MTBLIB_PACKAGE_NAME: &str = "io.medihbt.mtb.entity";
100/// > Required by MTBLib package tools. Do not modify.
101///
102/// MTBLib package version.
103pub const MTBLIB_PACKAGE_VERSION: &str = env!("CARGO_PKG_VERSION");
104
105mod tests;
mtb_entity_slab/lib.rs

mtb_entity_slab/
lib.rs
