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
noneDefault: fail fast on allocation failure and bounds violations.
secure_clearWipe memory before deallocation.
throws_on_allocation_failureReport allocation failure as a herbception instead of terminating.
throws_on_violationsReport container bounds violations as herbceptions.
throws_on_overflowReport size overflow as a herbception.
prefer_big_allocation_on_stackPrefer 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 codenative_global_allocator
Per-thread scratchnative_thread_local_allocator
Kernel or embedded arenaA custom allocator + generic_allocator_adapter
Secrets and key materialAn allocator with secure_clear
Recoverable allocation failureAn allocator with throws_on_allocation_failure
Bounds-checked containersAn 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.

Allocator mismatch is a type error. A container instantiated with one allocator cannot be assigned to a container with another. This is deliberate: the failure policy and the memory source travel with the type.

Key Takeaways