framealloc/
lib.rs

1//! # framealloc
2//!
3//! Intent-aware, thread-smart memory allocation for Rust game engines.
4//!
5//! ## Features
6//!
7//! - Frame-based arenas (bump allocation, reset per frame)
8//! - Thread-local fast paths (zero locks in common case)
9//! - Automatic ST → MT scaling
10//! - Optional Bevy integration
11//! - Allocation diagnostics & budgeting
12//! - Streaming allocator for large assets
13//! - Handle-based allocation with relocation support
14//! - Allocation groups for bulk freeing
15//! - Safe wrapper types (FrameBox, PoolBox, HeapBox)
16//! - std::alloc::Allocator trait implementations
17//!
18//! ## v0.2.0 Features
19//!
20//! - **Frame phases**: Named scopes within frames for profiling
21//! - **Frame checkpoints**: Save/restore points for speculative allocation
22//! - **Frame collections**: FrameVec, FrameMap with fixed capacity
23//! - **Tagged allocations**: First-class allocation attribution
24//! - **Scratch pools**: Cross-frame reusable memory
25//!
26//! ## Quick Start
27//!
28//! ```rust,no_run
29//! use framealloc::{SmartAlloc, AllocConfig};
30//!
31//! let alloc = SmartAlloc::new(AllocConfig::default());
32//!
33//! // Game loop
34//! alloc.begin_frame();
35//! let temp = alloc.frame_alloc::<[f32; 256]>();
36//! // ... use temp ...
37//! alloc.end_frame();
38//! ```
39
40#[allow(dead_code)]
41pub mod api;
42#[allow(dead_code)]
43pub mod diagnostics;
44pub mod handles;
45pub mod streaming;
46
47#[allow(dead_code)]
48mod allocators;
49#[allow(dead_code)]
50mod core;
51#[allow(dead_code)]
52mod sync;
53#[allow(dead_code)]
54mod util;
55
56#[cfg(feature = "bevy")]
57pub mod bevy;
58
59#[cfg(feature = "debug")]
60pub mod debug;
61
62#[cfg(feature = "tokio")]
63pub mod tokio;
64
65// Re-export public API at crate root for convenience
66pub use api::alloc::SmartAlloc;
67pub use api::config::AllocConfig;
68pub use api::scope::{FrameGuard, FrameScope};
69pub use api::stats::AllocStats;
70pub use api::tag::{AllocationIntent, AllocationTag};
71
72// Safe wrapper types
73pub use api::wrappers::{FrameBox, FrameSlice, PoolBox, HeapBox};
74
75// Allocator trait implementations (nightly only)
76#[cfg(feature = "nightly")]
77pub use api::allocator_impl::{FrameAllocator, PoolAllocator, HeapAllocator};
78
79// Allocation groups
80pub use api::groups::{GroupAllocator, GroupId, GroupHandle, GroupStats};
81
82// Handle-based allocation
83pub use allocators::handles::{Handle, HandleAllocator, HandleAllocatorStats, PinGuard};
84
85// Streaming allocation
86pub use allocators::streaming::{StreamId, StreamPriority, StreamState, StreamingAllocator, StreamingStats};
87
88// Budgets
89pub use core::budget::{BudgetEvent, BudgetManager, BudgetStatus, TagBudget};
90
91// Diagnostics - UI hooks
92pub use diagnostics::{DiagnosticsHooks, DiagnosticsEvent, SharedDiagnostics, MemoryGraphData};
93pub use diagnostics::{ProfilerHooks, ProfilerZone, MemoryEvent};
94pub use diagnostics::{AllocatorSnapshot, SnapshotHistory};
95
96// Diagnostics - Core types and predefined codes
97pub use diagnostics::{Diagnostic, DiagnosticKind};
98pub use diagnostics::{StrictMode, set_strict_mode, StrictModeGuard};
99pub use diagnostics::{FA001, FA002, FA003, FA101, FA102, FA201, FA202, FA301, FA302, FA401, FA402, FA901};
100
101// v0.2.0: Frame phases
102pub use api::phases::{Phase, PhaseGuard, PhaseTracker};
103pub use api::phases::{begin_phase, end_phase, current_phase, is_in_phase};
104
105// v0.2.0: Frame checkpoints
106pub use api::checkpoint::{FrameCheckpoint, CheckpointGuard, SpeculativeResult};
107
108// v0.2.0: Frame collections
109pub use api::frame_collections::{FrameVec, FrameVecIntoIter, FrameMap};
110
111// v0.2.0: Tagged allocations
112pub use api::tagged::{TagGuard, TagStack, with_tag, current_tag, tag_path};
113
114// v0.2.0: Scratch pools
115pub use api::scratch::{ScratchPool, ScratchRegistry, ScratchPoolHandle, ScratchPoolStats};
116
117// v0.3.0: Frame retention and promotion
118pub use api::retention::{RetentionPolicy, Importance, FrameRetained, PromotedAllocation, PromotionFailure};
119pub use api::promotion::{FrameSummary, PromotionResult, FailureBreakdown, TagSummary, PhaseSummary};
120
121// v0.4.0: Behavior filter and memory intent analysis
122pub use diagnostics::behavior::{
123    AllocKind, BehaviorFilter, BehaviorIssue, BehaviorReport, BehaviorThresholds, TagBehaviorStats,
124    FA501, FA502, FA510, FA520, FA530,
125};
126pub use diagnostics::{DiagnosticCode, DiagnosticLevel};
127
128// v0.6.0: Thread coordination and observability
129pub use api::transfer::{TransferHandle, TransferId, TransferState, TransferStats, TransferRegistry};
130pub use api::barrier::{FrameBarrier, FrameBarrierBuilder, BarrierStats};
131pub use api::lifecycle::{FrameEvent, LifecycleManager, LifecycleSummary, ThreadFrameStats, FrameLifecycleGuard};
132pub use api::thread_budget::{
133    ThreadBudgetManager, ThreadBudgetConfig, ThreadBudgetState, ThreadBudgetStats,
134    BudgetExceededPolicy, BudgetCheckResult,
135};
136pub use api::deferred_control::{
137    DeferredProcessing, DeferredConfig, DeferredController, DeferredStats as DeferredControlStats,
138    QueueFullPolicy, QueueResult, DeferredConfigBuilder,
139};
140
141// v0.7.0: IDE integration and snapshots
142pub use api::snapshot::{
143    Snapshot, SnapshotConfig, SnapshotEmitter, SnapshotSummary,
144    ThreadSnapshot, TagSnapshot, BudgetInfo, 
145    PromotionStats as SnapshotPromotionStats, 
146    TransferStats as SnapshotTransferStats,
147    DeferredStats as SnapshotDeferredStats, 
148    RuntimeDiagnostic, SNAPSHOT_VERSION,
149};
framealloc/lib.rs

framealloc/
lib.rs
