src/lib/trivial-allocator/README.md

# Trivial C++ Allocator Library

The trivial-allocator library provides a small, header-only C++ template
implementation of a trivial memory allocator for C++ code.  It can provide
variants of the C++ `new` expression syntax using an explicit allocator object.

These allocators are intended for two classes of use:

 1. startup allocations that stay live for the lifetime of the whole program
 2. grouping short-term allocations that will only ever be deallocated en masse

They are never appropriate for general allocation uses where objects are
created and deleted cyclically, since there is no reuse of unused memory.

These trivial "leaky" allocators do no real bookkeeping, so individual C++
object allocations cannot really be deallocated or reused.  They simply layer
on top of a simpler allocation functions (or callable object) that has some
means of allocating conveniently-sized (large) chunks, and then they parcel out
memory from those chunks.  Underlying memory allocated is either wholly leaked
or is all kept live during the lifetime of the allocation function object.

Trivial underlying "chunk" allocators to wrap inside the "leaky" allocator are
provided for consuming pre-allocated, fixed-sized buffers.  It's expected that
users of the library will provide simple chunk allocation functions appropriate
for their own context.

## BasicOwningAllocator

[<lib/trivial-allocator/basic-owning-allocator.h>](include/lib/trivial-allocator/basic-owning-allocator.h)
provides a variant of the leaky allocator that can use the same underlying
allocation functions.  However, where the leaky allocator simply loses track of
all the underlying allocations (leaks them), the owning allocator retains
ownership of every underlying allocation in the allocator object itself.  All
the piecemeal allocations point into one or more underlying allocations that
will be reclaimed en masse at the end of the allocator object's lifetime.

## PageAllocator

The `trivial_allocator::PageAllocator` template class in
[<lib/trivial-allocator/page-allocator.h>](include/lib/trivial-allocator/page-allocator.h)
provides an underlying allocator that gets whole-page chunks from the operating
system.
[<lib/trivial-allocator/posix.h>](include/lib/trivial-allocator/posix.h) and
[<lib/trivial-allocator/zircon.h>](include/lib/trivial-allocator/zircon.h)
provide classes to specialize `PageAllocator` for using POSIX `mmap`, and for
using the Zircon VMAR and VMO objects, respectively.

## SealedPageAllocator

The `trivial_allocator::SealedPageAllocator` template class in
[<lib/trivial-allocator/sealed-page-allocator.h>](include/lib/trivial-allocator/sealed-page-allocator.h)
is a variant of `PageAllocator` (above) meant for allocations that will be
written once and then "sealed", that is made read-only (and then never freed).

## `delete` support

A separate companion "stub-delete" library provides no-op `operator delete` and
`operator delete[]` functions.  Linking this in can be necessary not only when
`delete` or `delete[]` statements may be compiled into the program (even if
unreached), e.g. via std::unique_ptr or other "smart pointer" types, but also
when any class with virtual functions is used.  (The C++ ABI may require
special hidden virtual functions generated by the compiler that use `delete`.
These functions will always be linked in even if they can certainly never be
reached at runtime.)

The "panic-delete" library is an equivalent alternative whose operator
functions will panic like an assertion failure rather than silently leak the
memory.  It should be used in programs where dead code paths that can't be
avoided at link time are the only code paths (if any) that should ever use
`delete` statements.