Memory allocators

Several Crystal Space utility classes take optional memory allocators (e.g.

csArray<>). This allows clients to customize the memory allocation strategy used in a particular case.

For example, if you know that an array has a size below a certain threshold most of the time, you could utilize a LocalBufferAllocator<> which return memory from a fast local buffer, if possible - this is faster than using the heap.

As another example, when memory allocations follow a pattern where long-lived allocations are mixed with very short-lived allocations, heap fragmentation can occur when the short-lived allocations are freed. In that case it's beneficial to use a separate heap for the short-lived allocations; specific objects can use that heap via the allocator customization.

Allocators must obey the following methods and their semantics:

• void* Alloc(const size_t n) allocates n bytes of memory. Returns 0 if allocation fails.
• void Free (void* p) frees the pointer p. For debugging purposes it's usually a good idea to throw an assertion when p is invalid for an allocator.
• void* Realloc (void* p, size_t newSize) "resizes" the block at p to have a size of newSize bytes. If p is 0 then the call should have the same effect as an Alloc() with the specified size. Be aware that the returned pointer may be different from p! Also, if the reallocation fails, 0 is returned - however, the original memory block is still valid!
• void SetMemTrackerInfo (const char* info) is a debugging aid. If the allocator does memory tracking, some users will call this method to set a description of themselves which is displayed to allow easy identification of what object allocated how much memory. Implementation of this method is entirely optional and can be safely stubbed out.