Standard Template Library Programmer's Guide

Category: allocators

Component type: overview

Allocators encapsulate allocation and deallocation of memory. They provide a low-level interface that permits efficient allocation of many small objects; different allocator types represent different schemes for memory management.

Note that allocators simply allocate and deallocate memory, as opposed to creating and destroying objects. The STL also includes several low-level algorithms for manipulating uninitialized memory.

Note also that allocators do not attempt to encapsulate multiple memory models. The C++ language only defines a single memory model (the difference of two pointers, for example, is always ptrdiff_t ), and this memory model is the only one that allocators support. This is a major change from the definition of allocators in the original STL. [1]

The details of the allocator interface are still subject to change, and we do not guarantee that specific member functions will remain in future versions. You should think of an allocator as a "black box". That is, you may select a container's memory allocation strategy by instantiating the container template with a particular allocator [2], but you should not make any assumptions about how the container actually uses the allocator.

The available allocators are as follows. In most cases you shouldn't have to worry about the distinction: the default allocator, alloc , is usually the best choice.

vector V(100, 5.0); // Uses the default allocator.

vector local(V.begin(), V.end());

• Allocator

• alloc

• pthread_alloc

• single_client_alloc

• malloc_alloc

• raw_storage_iterator

• construct

• destroy

• uninitialized_copy

• uninitialized_fill

• uninitialized_fill_n

• get_temporary_buffer

• return_temporary_buffer

[1] The reason for this change is that the new interface reduces memory fragmentation, and that it allows an implementation that is both efficient and thread-safe.

[2] Different containers may use different allocators. You might, for example, have some containers that use the default allocator alloc and others that use pthread_alloc . Note, however, that vector and vector are distinct types.

Category: allocators

Component type: function

template

void construct(T1* p, const T2& value);

In C++, the operator new allocates memory for an object and then creates an object at that location by calling a constructor. Occasionally, however, it is useful to separate those two operations. [1] If p is a pointer to memory that has been allocated but not initialized, then construct(p, value) creates an object of type T1 at the location pointed to by p . The argument value is passed as an argument to T1 's constructor.

Defined in the standard header memory, and in the nonstandard backward-compatibility header algo.h. The construct algorithm is no longer part of the C++ standard; it was present in early drafts, and it is retained in this implementation for backward compatibility.

• T1 must have a constructor that takes a single argument of type T2 .

• p is a valid pointer that points to a region of memory whose size is at least sizeof(T1) .

• The memory pointed to by p is uninitialized. That is, no object has been constructed at the location p .

double* dp = (double*)malloc(sizeof(double));

construct(dp, 3);

assert(*dp == 3);

[1] In particular, construct , along with other low-level memory allocation primitives, is used to implement container classes.

Allocators, destroy , uninitialized_copy , uninitialized_fill , uninitialized_fill_n , raw_storage_iterator

Category: allocators

Component type: function

Destroy is an overloaded name; there are actually two destroy functions.

template

void destroy(T* pointer);

template

void destroy(ForwardIterator first, ForwardIterator last);

In C++, the operator delete destroys an object by calling its destructor, and then deallocates the memory where that object was stored. Occasionally, however, it is useful to separate those two operations. [1] Destroy calls an object's destructor without deallocating the memory where the object was stored.

The first version of destroy destroys the object pointed to by pointer by calling the destructor T::~T() . The memory pointed to by pointer is not deallocated, and can be reused for some other object.

The second version of destroy destroys all of the objects in the range of elements [first, last) . It is equivalent to calling destroy(&*i) for each iterator i in the range [first, last) .

Defined in the standard header memory, and in the nonstandard backward-compatibility header algo.h. The destroy algorithms are no longer part of the C++ standard; they were present in early drafts, and they are retained in this implementation for backward compatibility.