Ch26.19: Allocators
1. The Allocator Is Part of the Type
fast_io containers take the allocator as a template parameter. There is no global
allocator switch and no hidden fallback to malloc:
::fast_io::containers::vector<int, ::fast_io::native_global_allocator> v;
The convenient alias ::fast_io::vector<T> is the same container with
native_global_allocator filled in. A freestanding target writes the allocator
explicitly and chooses its own policy.
2. The Standard Allocators
| Name | Role | Module |
|---|---|---|
native_global_allocator |
The platform default: c_malloc, NT heap, Win32 heap, mimalloc or the freestanding allocator depending on the build. | fast_io |
native_typed_global_allocator<T> |
Typed view of the global allocator. | fast_io |
native_thread_local_allocator |
Thread-local allocator; defaults to the global allocator unless overridden. | fast_io |
native_typed_thread_local_allocator<T> |
Typed view of the thread-local allocator. | fast_io |
generic_allocator_adapter<A> |
Turns a raw allocator into the container interface. | fast_io |
typed_generic_allocator_adapter<A, T> |
Typed adapter over another adapter. | fast_io |
freestanding_global_allocator |
Declared by fast_io, defined by the target. | header-side |
The platform-specific allocators are selected by the build:
c_malloc_allocator, nt_rtlallocateheap_allocator,
win32_heapalloc_allocator, wincrt_malloc_dbg_allocator,
linux_kmalloc_allocator and mimalloc_allocator.
3. Adapter Flags
allocator_adapter_flags controls failure and security policy:
| Flag | Effect |
|---|---|
none | Default: fail fast on allocation failure and bounds violations. |
secure_clear | Wipe memory before deallocation. |
throws_on_allocation_failure | Report allocation failure as a herbception instead of terminating. |
throws_on_violations | Report container bounds violations as herbceptions. |
throws_on_overflow | Report size overflow as a herbception. |
prefer_big_allocation_on_stack | Prefer stack scratch space for large temporary allocations. |
The flags are OR-ed. A policy is part of the allocator type, so a container's failure behaviour is a compile-time property, not a global setting.
4. Allocation Result
The low-level contract returns allocation_least_result: a pointer and the
usable count. The “least” means the allocator may return more than requested. A custom
allocator implements the operations it supports; the adapter dispatches to its
_die or _try flavour.
| Operation shape | Meaning |
|---|---|
allocate_* | Allocate without zeroing. |
allocate_zero_* | Allocate and zero. |
allocate_aligned_* | Allocate with a requested alignment. |
allocate_aligned_conditional_zero_at_least_* |
The general form: alignment, size and a zero flag. |
reallocate_* | Grow/shrink an existing block. |
deallocate_* | Release a block. |
The _die variant terminates on failure. The _try variant reports
std::errc::not_enough_memory through the herbception channel. An adapter
converts between the two: in die mode a try-only allocator's error is caught and the
program terminates; in try mode a die-only allocator is a compile-time error.
5. Writing a Custom Allocator
Implement the smallest set your target needs and wrap it:
class my_arena
{
public:
static ::fast_io::allocation_least_result
allocate_aligned_conditional_zero_at_least_die(
::std::size_t alignment, ::std::size_t n, bool) noexcept;
static void deallocate_aligned_n(
void *p, ::std::size_t alignment, ::std::size_t n) noexcept;
};
using arena_alloc = ::fast_io::generic_allocator_adapter<my_arena>;
::fast_io::containers::vector<int, arena_alloc> v;
The adapter fills in the missing convenience operations by calling the general form. If
the allocator has a handle or status, use typed_generic_allocator_adapter or
the status adapter.
6. Choosing an Allocator
| Situation | Use |
|---|---|
| Normal hosted code | native_global_allocator |
| Per-thread scratch | native_thread_local_allocator |
| Kernel or embedded arena | A custom allocator +
generic_allocator_adapter |
| Secrets and key material | An allocator with
secure_clear |
| Recoverable allocation failure | An allocator with
throws_on_allocation_failure |
| Bounds-checked containers | An allocator with
throws_on_violations |
7. Module and Header Boundary
The fast_io module exports generic_allocator_adapter,
typed_generic_allocator_adapter, native_global_allocator,
native_typed_global_allocator, native_thread_local_allocator and
native_typed_thread_local_allocator, plus the platform allocators where the
build selects them. freestanding_global_allocator,
allocation_least_result and allocator_adapter_flags are
header-side today.
Key Takeaways
- The allocator is a container template parameter, not a global switch.
native_global_allocatorselects the platform's default source.generic_allocator_adapterandtyped_generic_allocator_adapteradapt raw allocators.allocator_adapter_flagscontrols secure clear, throwing and bounds policy.allocation_least_resultreturns a pointer plus usable size._dieterminates,_tryreports through herbceptions.freestanding_global_allocatoris declared by fast_io and defined by the target.