Memory and Free Blocks

Allocation handlers

Str Library can be adapted to the needs of different memory allocation schemes. By default, it will use the following allocators:

• Windows, STR_NO_RTLIBRARY not defined: C RTL-provided malloc() / free()
• Windows, STR_NO_RTLIBRARY defined: Windows HeapAlloc() family
• Linux: C RTL-provided malloc() / free()

If you want to implement a custom allocation scheme, you must define the conditional symbol STR_USER_ALLOCATOR. This will cause the default implementations of two Str class static methods - OS_malloc and OS_free - to be omitted from the library implementation.

In your application code, you must implement these two methods.  They should look similar to the following:

	static void* Str::OS_malloc(size_t size)
	{
		return MyOwnMalloc(size);
	}
	
	static void Str::OS_free(void* mem)
	{
		MyOwnFree(mem);		// Must behave correctly when passed a NULL pointer
	}

Overwrite checks in Debug builds

In Release builds, blocks allocated by Str Library take only as much memory as necessary to keep the fixed data plus the string bytes. However, when compiling in Debug mode, more memory will be taken. The extra bytes are used to keep a "fence" so that many typical buffer overwrite problems and "stray pointer" issues will be detected by Str Library and an assertion will be thrown.

Free block management

By default, Str Library will implement its own free block management mechanism.

The basic idea behind free block management is that, when a buffer is released, it is not returned to the underlying memory allocator, but instead is placed on a list of free blocks with a particular size. When someone requests a block with this size again, it will be available immediately.

For single-threaded and multi-threaded but single-CPU applications, this technique will usually improve performance quite a bit, esp. on Linux platforms. However, you may wish to disable the built-in mechanism in the following cases:

• To "shave off" several hundred bytes from your EXE or DLL if code size is very critical (e.g. a downloadable ActiveX)
• When you expect your code to run in an SMP environment (synchronization in Str Library related to free block management may be actually more expensive than the free block savings when using multiple CPUs)
• When you already use a third-party fast memory allocation library; there are several excellent implementations, some of which are multiplatform.

To disable free block management, declare STR_NO_BLOCK_CACHE in your configuration file.

The number of free blocks kept in the block pool is limited by the so-called "free cache factor", expressed with the conditional define STR_MAX_FREE_CACHE (which defaults to 5 unless explicitly defined in the configuration file)

In essence, a linear distribution of blocks is assumed.  For example, using the default factor of 5, a block granularity size of 64 and an upper limit on the cached free block size of 384, the maximum number of cached free objects would be: 5 blocks of size 384, 10 blocks of size 320, and so on till the smallest possible block size (64) of which there will be at most 25 free blocks in the queue.

See also: Str conditional defines