.Setup - WzrdIsTaken/Nabi-Allocator GitHub Wiki

Import

The easiest way to import the library is to download (or just copy/paste the contents of!) the single header file (!NabiAllocator.h) and add it to your project. Note: NabiAllocator uses C++ 20.

Config

At the top of the single header is a list of #defines. By enabling or disabling these you can configure NabiAllocator.

To learn more about the defines, please see the Configuration page. By default NabiAllocator is setup to be as general purpose as possible, though you may want to route asserts and logging through your project's system and use the short namespace. Details on both these topics can be found on the Configuration page.

Initialization

To initialize NabiAllocator, just paste the following code into your main file. See below for a more detailed explanation.

#include "!NabiAllocator.h"

// Before your application's main loop starts
using namespace nabi_allocator;
HeapZone<DefaultFreeListAllocator> heapZone = { HeapZoneBase::c_NoParent, 1_GB , "HeapZone" };
NA_SET_HEAP_ZONE_SCOPE(&heapZone, c_NullMemoryTag);

To initialize NabiAllocator, you first need to create a HeapZone. For this to be global, do it before your main application loop.

HeapZone<[allocator type (1)]> heapZone = { [zone parent (2)], [zone size (3)], [zone debug name (4)] };

  1. Out of the box NabiAllocator has two types of allocators - FreeListAllocator and StackAllocator. Both allocators can be customised with their respective settings, but both also have a typedef Default variant for simplicity. For a global allocator the FreeListAllocator is the best choice, so for a quick start template the HeapZone with DefaultFreeListAllocator. To learn more about the allocators, see the Crash Course.
  2. A HeapZone by default uses malloc to create its pool of memory. However, if a zone has a parent then the its pool of memory will be allocated from the parents pool. If a zone does not have a parent, like in this case, use the constant HeapZoneBase::c_NoParent.
  3. HeapZones must be initialized with a size (which must be a multiple of 8). This size refers to the amount of memory the HeapZone will represent. You can use the operator overloads defined in the inline namespace memory_operators for brevity. For example, the zone size could be set to 2_GB. For an idea of how big the heap zone should be, you can use Visual Studio's diagnostic tools or your IDEs equivalent and profile your application. Be careful that you don't try and allocate too much memory all at once. Don't worry though, if an allocation exceeds a heap zone's size then it will fall back to malloc as long as NA_MALLOC_IF_OUT_OF_MEMORY is defined.
  4. Finally, a debug string name can be set for the zone. This string will only be stored if NA_DEBUG is defined.

The second and final step is to set the HeapZone as the active zone. You can do this with the NA_SET_HEAP_ZONE_SCOPE macro. This macro takes in two arguments, a HeapZone and a memory_tag. We won't worry about memory tagging yet, so you can just use the c_NullMemoryTag constant.

There you have it! That's all you need to do to setup NabiAllocator. As long as NA_OVERRIDE_NEW_DELETE is defined all heap allocations will be automatically routed through this HeapZone.

And if you want even more brevity you can combine these two lines into one with the NA_MAKE_HEAP_ZONE_AND_SET_SCOPE macro like so: NA_MAKE_HEAP_ZONE_AND_SET_SCOPE(HeapZone<[allocator type]>, [zone parent], [zone size], [zone debug name], [memory tag]);.

More Information

For more information about NabiAllocator check out the Crash Course page. Some sections I recommend are:

For code examples of NabiAllocator in use, see the FullWorkflow.cpp file.