tree: 27775c7fbfa9a051f333b3dfbdb09512058b8549 [path history] [tgz]
  1. include/
  2. meta/
  3. basic-leaky-allocator-tests.cc
  4. basic-owning-allocator-tests.cc
  5. BUILD.gn
  6. delete-tests.cc
  7. new-tests.cc
  8. page-allocator-tests.cc
  9. panic-delete.cc
  10. README.md
  11. single-heap-allocator-tests.cc
  12. stub-delete.cc
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> 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> provides an underlying allocator that gets whole-page chunks from the operating system. <lib/trivial-allocator/posix.h> and <lib/trivial-allocator/zircon.h> provide classes to specialize PageAllocator for using POSIX mmap, and for using the Zircon VMAR and VMO objects, respectively.

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.