Crate framealloc 

framealloc

Intent-aware, thread-smart memory allocation for Rust game engines.

Features

• Frame-based arenas (bump allocation, reset per frame)
• Thread-local fast paths (zero locks in common case)
• Automatic ST → MT scaling
• Optional Bevy integration
• Allocation diagnostics & budgeting
• Streaming allocator for large assets
• Handle-based allocation with relocation support
• Allocation groups for bulk freeing
• Safe wrapper types (FrameBox, PoolBox, HeapBox)
• std::alloc::Allocator trait implementations

v0.2.0 Features

• Frame phases: Named scopes within frames for profiling
• Frame checkpoints: Save/restore points for speculative allocation
• Frame collections: FrameVec, FrameMap with fixed capacity
• Tagged allocations: First-class allocation attribution
• Scratch pools: Cross-frame reusable memory

Quick Start

use framealloc::{SmartAlloc, AllocConfig};

let alloc = SmartAlloc::new(AllocConfig::default());

// Game loop
alloc.begin_frame();
let temp = alloc.frame_alloc::<[f32; 256]>();
// ... use temp ...
alloc.end_frame();

Re-exports

pub use api::alloc::SmartAlloc;

pub use api::config::AllocConfig;

pub use api::scope::FrameGuard;

pub use api::scope::FrameScope;

pub use api::stats::AllocStats;

pub use api::tag::AllocationIntent;

pub use api::tag::AllocationTag;

pub use api::wrappers::FrameBox;

pub use api::wrappers::FrameSlice;

pub use api::wrappers::PoolBox;

pub use api::wrappers::HeapBox;

pub use api::groups::GroupAllocator;

pub use api::groups::GroupId;

pub use api::groups::GroupHandle;

pub use api::groups::GroupStats;

pub use diagnostics::DiagnosticsHooks;

pub use diagnostics::DiagnosticsEvent;

pub use diagnostics::SharedDiagnostics;

pub use diagnostics::MemoryGraphData;

pub use diagnostics::ProfilerHooks;

pub use diagnostics::ProfilerZone;

pub use diagnostics::MemoryEvent;

pub use diagnostics::AllocatorSnapshot;

pub use diagnostics::SnapshotHistory;

pub use diagnostics::Diagnostic;

pub use diagnostics::DiagnosticKind;

pub use diagnostics::StrictMode;

pub use diagnostics::set_strict_mode;

pub use diagnostics::StrictModeGuard;

pub use diagnostics::FA001;

pub use diagnostics::FA002;

pub use diagnostics::FA003;

pub use diagnostics::FA101;

pub use diagnostics::FA102;

pub use diagnostics::FA201;

pub use diagnostics::FA202;

pub use diagnostics::FA301;

pub use diagnostics::FA302;

pub use diagnostics::FA401;

pub use diagnostics::FA402;

pub use diagnostics::FA901;

pub use api::phases::Phase;

pub use api::phases::PhaseGuard;

pub use api::phases::PhaseTracker;

pub use api::phases::begin_phase;

pub use api::phases::end_phase;

pub use api::phases::current_phase;

pub use api::phases::is_in_phase;

pub use api::checkpoint::FrameCheckpoint;

pub use api::checkpoint::CheckpointGuard;

pub use api::checkpoint::SpeculativeResult;

pub use api::frame_collections::FrameVec;

pub use api::frame_collections::FrameVecIntoIter;

pub use api::frame_collections::FrameMap;

pub use api::tagged::TagGuard;

pub use api::tagged::TagStack;

pub use api::tagged::with_tag;

pub use api::tagged::current_tag;

pub use api::tagged::tag_path;

pub use api::scratch::ScratchPool;

pub use api::scratch::ScratchRegistry;

pub use api::scratch::ScratchPoolHandle;

pub use api::scratch::ScratchPoolStats;

pub use api::retention::RetentionPolicy;

pub use api::retention::Importance;

pub use api::retention::FrameRetained;

pub use api::retention::PromotedAllocation;

pub use api::retention::PromotionFailure;

pub use api::promotion::FrameSummary;

pub use api::promotion::PromotionResult;

pub use api::promotion::FailureBreakdown;

pub use api::promotion::TagSummary;

pub use api::promotion::PhaseSummary;

pub use diagnostics::behavior::AllocKind;

pub use diagnostics::behavior::BehaviorFilter;

pub use diagnostics::behavior::BehaviorIssue;

pub use diagnostics::behavior::BehaviorReport;

pub use diagnostics::behavior::BehaviorThresholds;

pub use diagnostics::behavior::TagBehaviorStats;

pub use diagnostics::behavior::FA501;

pub use diagnostics::behavior::FA502;

pub use diagnostics::behavior::FA510;

pub use diagnostics::behavior::FA520;

pub use diagnostics::behavior::FA530;

pub use diagnostics::DiagnosticCode;

pub use diagnostics::DiagnosticLevel;

pub use api::transfer::TransferHandle;

pub use api::transfer::TransferId;

pub use api::transfer::TransferState;

pub use api::transfer::TransferStats;

pub use api::transfer::TransferRegistry;

pub use api::barrier::FrameBarrier;

pub use api::barrier::FrameBarrierBuilder;

pub use api::barrier::BarrierStats;

pub use api::lifecycle::FrameEvent;

pub use api::lifecycle::LifecycleManager;

pub use api::lifecycle::LifecycleSummary;

pub use api::lifecycle::ThreadFrameStats;

pub use api::lifecycle::FrameLifecycleGuard;

pub use api::thread_budget::ThreadBudgetManager;

pub use api::thread_budget::ThreadBudgetConfig;

pub use api::thread_budget::ThreadBudgetState;

pub use api::thread_budget::ThreadBudgetStats;

pub use api::thread_budget::BudgetExceededPolicy;

pub use api::thread_budget::BudgetCheckResult;

pub use api::deferred_control::DeferredProcessing;

pub use api::deferred_control::DeferredConfig;

pub use api::deferred_control::DeferredController;

pub use api::deferred_control::DeferredStats as DeferredControlStats;

pub use api::deferred_control::QueueFullPolicy;

pub use api::deferred_control::QueueResult;

pub use api::deferred_control::DeferredConfigBuilder;

pub use api::snapshot::Snapshot;

pub use api::snapshot::SnapshotConfig;

pub use api::snapshot::SnapshotEmitter;

pub use api::snapshot::SnapshotSummary;

pub use api::snapshot::ThreadSnapshot;

pub use api::snapshot::TagSnapshot;

pub use api::snapshot::BudgetInfo;

pub use api::snapshot::PromotionStats as SnapshotPromotionStats;

pub use api::snapshot::TransferStats as SnapshotTransferStats;

pub use api::snapshot::DeferredStats as SnapshotDeferredStats;

pub use api::snapshot::RuntimeDiagnostic;

pub use api::snapshot::SNAPSHOT_VERSION;

Modules

api

Public API for framealloc.

diagnostics

Diagnostics and UI integration hooks.

handles

Handle-based allocation with relocation support.

streaming

Streaming allocator for large assets.

Macros

fa_assert

Assert a condition or emit a diagnostic.

fa_compile_error

Compile-time diagnostic error.

fa_compile_warning

Compile-time diagnostic warning (via deprecated).

fa_debug

Debug-only diagnostic (completely removed in release).

fa_diagnostic

Emit a runtime diagnostic.

fa_diagnostic_ctx

Emit a runtime diagnostic with captured context.

fa_emit

Emit a predefined diagnostic by code.

fa_emit_ctx

Emit a predefined diagnostic with context.

Structs

BudgetManager

Manages memory budgets and limits with per-tag tracking.

Handle

A stable handle to allocated memory.

HandleAllocator

Handle-based allocator with relocation support.

HandleAllocatorStats

Statistics for the handle allocator.

PinGuard

RAII guard for pinning a handle.

StreamId

Unique identifier for a streaming allocation.

StreamingAllocator

Streaming allocator for large assets.

StreamingStats

Statistics about streaming allocations.

TagBudget

Budget configuration and current usage for a specific tag.

Enums

BudgetEvent

Events emitted by the budget manager.

BudgetStatus

Result of a budget check.

StreamPriority

Priority level for streaming allocations.

StreamState

State of a streaming allocation.