<allocators>

Defines several templates that help allocate and free memory blocks for node-based containers.

#include <allocators>

Remarks

The <allocators> header provides six allocator templates that can be used to select memory-management strategies for node-based containers. For use with these templates, it also provides several different synchronization filters to tailor the memory-management strategy to a variety of different multithreading schemes (including none). Matching a memory management strategy to the known memory usage patterns, and synchronization requirements, of a particular application can often increase the speed or reduce the overall memory requirements of an application.

The allocator templates are implemented with reusable components that can be customized or replaced to provide additional memory-management strategies.

The node-based containers in the Standard C++ library (std::list, std::set, std::multiset, std::map and std::multimap) store their elements in individual nodes. All the nodes for a particular container type are the same size, so the flexibility of a general-purpose memory manager is not needed. Because the size of each memory block is known at compile time, the memory manager can be much simpler and faster.

When used with containers that are not node-based (such as the Standard C++ library containers std::vector std::deque, and std::basic_string), the alllocator templates will work correctly, but are not likely to provide any performance improvement over the default allocator.

An allocator is a template class that describes an object that manages storage allocation and freeing for objects and arrays of objects of a designated type. Allocator objects are used by several container template classes in the Standard C++ library.

The allocators are all templates of this type:

template<class Type>

class allocator;

where the template argument Type is the type managed by the allocator instance. The Standard C++ library provides a default allocator, template class allocator, which is defined in <memory>. The <allocators> header provides the following allocators:

• allocator_newdel

• allocator_unbounded

• allocator_fixed_size

• allocator_variable_size

• allocator_suballoc

• allocator_chunklist

Use an appropriate instantiation of an allocator as the second type argument when creating a container, such as the following code example.

#include <list>

#include <allocators>

std::list<int, stdext::allocators::allocator_chunklist<int> > _List0;

_List0 allocates nodes with allocator_chunklist and the default synchronization filter.

Use the macro ALLOCATOR_DECL (<allocators>) to create allocator templates with synchronization filters other than the default:

#include <list>

#include <allocators>

ALLOCATOR_DECL(CACHE_CHUNKLIST, stdext::allocators::sync_per_thread, Alloc);

std::list<int, alloc<int> > _List1;

_Lst1 allocates nodes with allocator_chunklist and the sync_per_thread synchronization filter.

A block allocator is a cache or a filter. A cache is a template class that takes one argument of type std::size_t. It defines a block allocator that allocates and deallocates memory blocks of a single size. It must obtain memory using operator new, but it need not make a separate call to operator new for each block. It may, for example, suballocate from a larger block or cache deallocated blocks for subsequent reallocation.

With a compiler that cannot compile rebind the value of the std::size_t argument used when the template was instantiated is not necessarily the value of the argument _Sz passed to a cache's member functions allocate and deallocate.

<allocators> provides the following cache templates:

• cache_freelist

• cache_suballoc

• cache_chunklist

A filter is a block allocator that implements its member functions using another block allocator which is passed to it as a template argument. The most common form of filter is a synchronization filter, which applies a synchronization policy to control access to the member functions of an instance of another block allocator. <allocators> provides the following synchronization filters:

• sync_none

• sync_per_container

• sync_per_thread

• sync_shared

<allocators> also provides the filter rts_alloc, which holds multiple block allocator instances and determines which instance to use for allocation or deallocation at runtime instead of at compile time. It is used with compilers that cannot compile rebind.

A synchronization policy determines how an allocator instance handles simultaneous allocation and deallocation requests from multiple threads. The simplest policy is to pass all requests directly through to the underlying cache object, leaving synchronization management to the user. A more complex policy could be to use a mutex to serialize access to the underlying cache object.

If a compiler supports compiling both single-threaded and multi-threaded applications, the default synchronization filter for single-threaded applications is sync_none; for all other cases it is sync_shared.

The cache template cache_freelist takes a max class argument which determines the maximum number of elements to be stored in the free list.

<allocators> provides the following max classes:

• max_none

• max_unbounded

• max_fixed_size

• max_variable_size

Macros

Operators

Classes

Requirements

Header: <allocators>

Namespace: stdext

See Also

Other Resources

C++ Standard Library Header Files