whalloc  WhallocConfig

whalloc configuration options

See also: WhallocBasics

WHALLOC_BITNESS and whalloc_size_t

WHALLOC_BITNESS is a compile-time constant defined in the main header. It describes the number of bits of storage the allocator uses as its "atomic" unit. It defaults to 16, but 8 and 32 are also legal (but you cannot do much with an 8-bit memory pool). The maximum managed memory size for any allocator object is (2^WHALLOC_BITNESS), and no single allocation may be larger than 2^(WHALLOC_BITNESS-1) bytes (32k for the default of 16 bits). The seemingly low value of 16 was choses as the default because the sizeof() space savings, compared to a bitness of 32, are significant in use cases the first whalloc allocators were designed for.

WHALLOC_BITNESS it used to determine the type of whalloc_size_t, which is a fixed-sized integer type used for all calculations. whalloc_size_t is the same size, in bytes, as (WHALLOC_BITNESS/8). Thus it is uint8_t when WHALLOC_BITNESS=8, uint16_t for WHALLOC_BITNESS=16, and uint32_t for WHALLOC_BITNESS=32.

whalloc_size_t is used as a member value in the various classes, and changing this changes the size of those classes. For allocators which store their managed data in their managed memory space (most do), a larger bitness value means they will reserve more of the managed memory for themselves.

The hashtable allocator is especially sensitive to changes in WHALLOC_BITNESS, as it requires sizeof(whalloc_size_t) bytes of storage for each block it manages. The minimum block size the hashtable can effectively work with is sizeof(whalloc_size_t) (requiring a 50% memory overhead!) because smaller block sizes means more blocks to manage, which means more table entries are needed to manage them (each costing sizeof(whalloc_size_t) bytes).

The bitmap allocator's internal memory management is not directly affected by WHALLOC_BITNESS with one small exception: the whalloc_bt class can be configured to include a small internal memory buffer with a default size of (2*WHALLOC_BITNESS) bytes. If it can fit its table in those bytes, it will use them instead of the client's memory for storing its table.