electronicarts / EASTL

EASTL stands for Electronic Arts Standard Template Library. It is an extensive and robust implementation that has an emphasis on high performance.
BSD 3-Clause "New" or "Revised" License
7.82k stars 905 forks source link

Outdated/incorrect documentation for use of containers with fixed allocators #484

Open Woazboat opened 1 year ago

Woazboat commented 1 year ago

When using a standard non-fixed container (e.g. list, map, etc...) with a fixed allocator like eastl::fixed_pool or eastl::fixed_node_allocator, the default container constructor (/the default parameter for the allocator) attempts to construct the allocator using the container name string as the first parameter.

e.g. for map:

// Constructor
map(const allocator_type& allocator = EASTL_MAP_DEFAULT_ALLOCATOR);
// i.e. 
map(const allocator_type& allocator = allocator_type("EASTL map"));

The fixed allocator constructors are declared as:

explicit fixed_pool(void* pMemory = NULL);
fixed_node_allocator(void* pNodeBuffer);

This breaks and fails to compile when a fixed allocator is used for a default constructed container since the fixed allocators do not use the name as the first constructor parameter. (Actually it attempts to use the const char* string as the void* memory buffer argument and the only reason it fails to compile is because it expects a non-const pointer, otherwise it would silently accept it which might be even worse.)

The example that's given in the documentation does not actually work due to this issue. https://eastl.docsforge.com/master/faq/#cont10-how-do-i-use-a-memory-pool-with-a-container

char buffer[256];

list<Widget, fixed_pool> myList;
myList.get_allocator().init(buffer, 256);
Woazboat commented 1 year ago

Okay, seems like this is more of an issue with (outdated?) documentation. eastl::fixed_allocator takes a name string as the first argument and therefore works properly. eastl::fixed_pool and eastl::fixed_node_allocator are in the internal folder, so I guess they don't need to conform to the convention.

The documentation here should be changed to use eastl::fixed_allocator instead of eastl::fixed_pool.