13.36 <memory>

The <memory> header declares function and class templates for allocating and using memory, such as the auto_ptr<> smart pointer, algorithms for working with uninitialized memory, and a standard allocator for use with the standard containers.

The auto_ptr class template provides a simple ownership model for working with pointers. It can be extremely useful for writing exception-safe code. On the other hand, copying an auto_ptr<> object does not produce an exact copy (ownership of the pointer is transferred), so auto_ptr<> objects cannot be stored in standard containers.

Several functions work with uninitialized memory, which can be helpful when implementing a container. For example, an implementation of vector must allocate an uninitialized array of objects and initialize elements of the array as they are needed. The uninitialized_ . . . functions can come in handy for that purpose.

The allocator class template manages memory allocation and deallocation and the construction and destruction of objects in the memory it manages. It is the default allocator for all the standard containers.

allocator class template

Encapsulates memory allocation and deallocation

template <class T>

class allocator {

public:

  typedef size_t size_type;

  typedef ptrdiff_t difference_type;

  typedef T* pointer;

  typedef const T* const_pointer;

  typedef T& reference;

  typedef const T& const_reference;

  typedef T value_type;

  template <class U> struct rebind {

    typedef allocator<U> other;

  };

  allocator(  ) throw(  );

  allocator(const allocator&) throw(  );

  template <class U> allocator(const allocator<U>&) throw(  );

  ~allocator(  ) throw(  );

  pointer address(reference x) const;

  const_pointer address(const_reference x) const;

  pointer allocate(size_type, allocator<void>::const_pointer hint = 0);

  void deallocate(pointer p, size_type n);

  size_type max_size(  ) const throw(  );

  void construct(pointer p, const T& val);

  void destroy(pointer p);

};

The allocator class template encapsulates basic allocation and deallocation functions. The standard containers rely on allocators for memory management and use allocator as the default allocator.

Most programmers do not need to use allocator, which offers few advantages over plain new and delete. However, if you want to write your own container, or provide a custom allocator for the standard containers, you should take the time to understand allocator.

Perhaps the easiest way to understand allocator is to take a look at a trivial implementation in Example 13-30. Note that a library might have a more complicated implementation to handle multithreading, improve performance, etc. Some libraries offer allocators for special purposes, such as allocating memory that can be shared among multiple processes. This particular implementation is just a sample.

Example

Example 13-30. Sample allocator implementation

template<typename T>

class myallocator {

public:

  typedef std::size_t size_type;

  typedef std::ptrdiff_t difference_type;

  typedef T* pointer;

  typedef const T* const_pointer;

  typedef T& reference;

  typedef const T& const_reference;

  typedef T value_type;

  template <class U> struct rebind {

    typedef myallocator<U> other;

  };

  myallocator(  ) throw(  )                          {}

  myallocator(const myallocator&) throw(  )          {}

  template <class U>

  myallocator(const myallocator<U>&) throw(  )       {}

  ~myallocator(  ) throw(  )                         {}

  pointer address(reference x) const                 {return &x;}

  const_pointer address(const_reference x) const     {return &x;}

  pointer allocate(size_type n, void* hint = 0) {

    return static_cast<T*>(::operator new (n * sizeof(T)) );

  }

  void deallocate(pointer p, size_type n) {

    ::operator delete(static_cast<void*>(p));

  }

  size_type max_size(  ) const throw(  ) {

    return std::numeric_limits<size_type>::max(  ) / sizeof(T);

  }

  void construct(pointer p, const T& val) {

    new(static_cast<void*>(p)) T(val);

  }

  void destroy(pointer p) {

    p->~T(  );

  }

};

   

template<typename T>

bool operator==(const myallocator<T>&, const myallocator<T>&)

{

  return true;

}

   

template<typename T>

bool operator!=(const myallocator<T>&, const myallocator<T>&)

{

   return false;

}

   

template<>

class myallocator<void> {

public:

  typedef void* pointer;

  typedef const void* const_pointer;

  typedef void value_type;

  template <class U> struct rebind {

    typedef myallocator<U> other;

  };

};

The following are the members of allocator:

allocator( ) throw( )

allocator(const allocator&) throw( )

template<class U> allocator(const allocator&) throw( )

Constructs a new allocator object, possibly copying an existing allocator. Remember that all instances must be equivalent, so an allocator typically does not have any data members to initialize.

pointer address(reference x) const

const_pointer address(const_reference x) const

Returns the address of x, that is, &x.

pointer allocate(size_type n, allocator<void>::const_pointer hint = 0)

Calls the global new operator to allocate enough memory to hold n objects of type T. The hint argument must be 0 or a pointer obtained from a prior call to allocate that has not been passed to deallocate. The return value is a pointer to the newly allocated memory. If the memory cannot be allocated, bad_alloc is thrown.

An implementation might use hint to improve performance.

typedef const T* const_pointer

A type for a pointer to const. In a custom allocator, the type should be equivalent to const T*.

typedef const T& const_reference

A type for a const lvalue. In a custom allocator, the type should be equivalent to const T&.

void construct(pointer p, const T& val)

Calls the global new operator to construct an instance of T with value val using the memory that p points to. That is, it calls new(static_cast<void*>(p)) T(val).

void deallocate(pointer p, size_type n)

Calls the global delete operator to free the memory that p points to. The n argument is the number of items of type Tthe same value passed to allocate.

void destroy(pointer p)

Calls the destructor for the object at address p. That is, it calls reinterpret_cast<T*>(p)->~T( ).

typedef ptrdiff_t difference_type

A type that represents the difference of any two pointers that the allocator returns from allocate( ).

size_type max_size( ) const throw( )

Returns the maximum size that can be passed to allocate.

typedef T* pointer

A pointer type. In a custom allocator, the type should be equivalent to T*.

template <class U> struct rebind

Binds the allocator object to a different value type. The rebind class has a single typedef, other, which is an instance of the same allocator template, but with U as the template parameter. The rebind template is necessary for standard containers that allocate helper objects, such as link nodes, rather than allocating values directly. If you are not implementing a standard container, you probably don't need to understand rebind.

typedef T& reference

An lvalue type. In a custom allocator, the type should be equivalent to T&.

typedef size_t size_type

A type that can represent the size of the largest allocation request.

typedef T value_type

The type of allocated values, which is typically T.

Example

Example 13-31. Sample uses of auto_ptr

class brush {  . . .  };

class pen {  . . .  };

   

// A function can return an auto_ptr<> object.

std::auto_ptr<brush> default_brush(  )

{

  return std::auto_ptr<brush>(new brush);

}

   

class DisplayContext {

  // Display or graphics context for drawing on a window.

public:

  DisplayContext(  )

  : brush_(default_brush(  )), pen_(new pen) {...}

   . . . 

private:

  // Make sure caller never tries to copy or assign

  // DisplayContext, but uses only objects that are

  // managed by auto_ptr<>.

  DisplayContext(const DisplayContext& dc);

  DisplayContext& operator=(const DisplayContext& dc);

  // Automatically manage lifetime of the pen and brush.

  // When the DisplayContext is freed, so are the pen

  // and brush instances.

  std::auto_ptr<brush> brush_;

  std::auto_ptr<pen>   pen_;

};

   

void repaint(  )

{

  // Allocate a new display context. Use auto_ptr to ensure

  // that it will be freed automatically.

  std::auto_ptr<DisplayContext> dc(new DisplayContext(  ));

  // Draw stuff on the display context.

  dc->draw( . . . );

  // No need to call release; the display context is

  // automatically released when repaint(  ) returns.

}

   

int main(  )

{

  std::auto_ptr<DisplayContext> dc1(new DisplayContext);

  std::auto_ptr<DisplayContext> dc2(dc1);

   

  dc1 = dc2;

  repaint(  );

}

The following are the members of auto_ptr:

explicit auto_ptr(T* p = 0) throw( ): Initializes the auto_ptr object to own the pointer p.
auto_ptr(auto_ptr& x) throw( )
template<class U> auto_ptr(auto_ptr& x) throw( ): Initializes the auto_ptr object with the pointer returned from x.release( ). In the second version, the type U* must be implicitly convertible to T*. Note that x is not const. It is not possible to copy a const auto_ptr because to do so would break the ownership rules.
auto_ptr(auto_ptr_ref<T> r) throw( ): Initializes the auto_ptr object with the pointer obtained from calling release on r's auto_ptr.
~auto_ptr( ) throw( ): Deletes the owned pointer (e.g., delete get( )).
T* get( ) const throw( ): Returns the owned pointer.
T* release( ) throw( ): Returns get( ) and resets the owned pointer to 0.
void reset(T* p = 0) throw( ): Deletes the owned pointer (if it is not equal to p) and saves p as the new owned pointer.
template<class U> operator auto_ptr_ref( ) throw( ): Returns a temporary auto_ptr_ref object that owns the pointer. The pointer must be convertible to U*. Ownership is released and transferred to the new auto_ptr_ref object.
template<class U> operator auto_ptr( ) throw( ): Returns a new auto_ptr object. The owned pointer is converted to type U*, and ownership is transferred to the new auto_ptr object.
auto_ptr& operator=(auto_ptr& x) throw( )
template<class U>
auto_ptr& operator=(auto_ptr& x) throw( )
auto_ptr& operator=(auto_ptr_ref<T> r) throw( ): Transfers ownership of the pointer that is owned by x or by the auto_ptr object held by r to *this. That is, it calls reset(x.release( )).
T& operator*( ) const throw( ): Returns *get( ). If the owned pointer is a null pointer, the behavior is undefined.
T* operator->( ) const throw( ): Returns get( ).

13.36 <memory>

Example

Example 13-30. Sample allocator implementation

See Also

See Also

Example

Example 13-31. Sample uses of auto_ptr

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also