| Home | Libraries | People | FAQ | More

## Class template allocator

boost::container::allocator

## Synopsis

    // In header: <boost/container/allocator.hpp>

    template<typename T, unsigned Version = 2,
             unsigned int AllocationDisableMask = 0>
    class allocator {
    public:
      // types
      typedef T              value_type;
      typedef T *            pointer;
      typedef const T *      const_pointer;
      typedef T &            reference;
      typedef const T &      const_reference;
      typedef std::size_t    size_type;
      typedef std::ptrdiff_t difference_type;
      typedef unspecified    version;

      // member classes/structs/unions
      template<typename T2>
      struct rebind {
        // types
        typedef allocator< T2, Version, AllocationDisableMask > other;
      };

      // construct/copy/destruct
      allocator() noexcept;
      allocator(const allocator &) noexcept;
      template<typename T2> allocator(const allocator< T2 > &) noexcept;

      // public member functions
      pointer allocate(size_type, const void * = 0);
      void deallocate(pointer, size_type) noexcept;
      size_type max_size() const noexcept;
      pointer allocation_command(allocation_type, size_type, size_type &,
                                 pointer &);
      size_type size(pointer) const noexcept;
      pointer allocate_one();
      void allocate_individual(std::size_t, multiallocation_chain &);
      void deallocate_one(pointer) noexcept;
      void deallocate_individual(multiallocation_chain &) noexcept;
      void allocate_many(size_type, std::size_t, multiallocation_chain &);
      void allocate_many(const size_type *, size_type, multiallocation_chain &);
      void deallocate_many(multiallocation_chain &) noexcept;

      // friend functions
      friend void swap(self_t &, self_t &) noexcept;
      friend bool operator==(const allocator &, const allocator &) noexcept;
      friend bool operator!=(const allocator &, const allocator &) noexcept;

      // private member functions
      pointer priv_allocation_command(allocation_type, std::size_t, size_type &,
                                      pointer &);
    };

## Description

This class is an extended STL-compatible that offers advanced allocation mechanism (in-place expansion, shrinking, burst-allocation...)

This allocator is a wrapper around a modified DLmalloc. If Version is 1, the allocator is a STL conforming allocator. If Version is 2, the allocator offers advanced expand in place and burst allocation capabilities.

AllocationDisableMask works only if Version is 2 and it can be an inclusive OR of allocation types the user wants to disable.

### `allocator` public construct/copy/destruct

1.     allocator() noexcept;

   Default constructor Never throws

2.     allocator(const allocator &) noexcept;

   Constructor from other allocator. Never throws

3.     template<typename T2> allocator(const allocator< T2 > &) noexcept;

   Constructor from related allocator. Never throws

### `allocator` public member functions

1.     pointer allocate(size_type count, const void * hint = 0);

   Allocates memory for an array of count elements. Throws std::bad_alloc if there is no enough memory If Version is 2, this allocated memory can only be deallocated with deallocate() or (for Version == 2) deallocate_many()

2.     void deallocate(pointer ptr, size_type) noexcept;

   Deallocates previously allocated memory. Never throws

3.     size_type max_size() const noexcept;

   Returns the maximum number of elements that could be allocated. Never throws

4.     pointer allocation_command(allocation_type command, size_type limit_size,
                                  size_type & prefer_in_recvd_out_size,
                                  pointer & reuse);

   An advanced function that offers in-place expansion shrink to fit and new allocation capabilities. Memory allocated with this function can only be deallocated with deallocate() or deallocate_many(). This function is available only with Version == 2

5.     size_type size(pointer p) const noexcept;

   Returns maximum the number of objects the previously allocated memory pointed by p can hold. Memory must not have been allocated with allocate_one or allocate_individual. This function is available only with Version == 2

6.     pointer allocate_one();

   Allocates just one object. Memory allocated with this function must be deallocated only with deallocate_one(). Throws bad_alloc if there is no enough memory This function is available only with Version == 2

7.     void allocate_individual(std::size_t num_elements,
                                multiallocation_chain & chain);

   Allocates many elements of size == 1. Elements must be individually deallocated with deallocate_one() This function is available only with Version == 2

8.     void deallocate_one(pointer p) noexcept;

   Deallocates memory previously allocated with allocate_one(). You should never use deallocate_one to deallocate memory allocated with other functions different from allocate_one() or allocate_individual.

9.     void deallocate_individual(multiallocation_chain & chain) noexcept;

   Deallocates memory allocated with allocate_one() or allocate_individual(). This function is available only with Version == 2

10.     void allocate_many(size_type elem_size, std::size_t n_elements,
                           multiallocation_chain & chain);

    Allocates many elements of size elem_size. Elements must be individually deallocated with deallocate() This function is available only with Version == 2

11.     void allocate_many(const size_type * elem_sizes, size_type n_elements,
                           multiallocation_chain & chain);

    Allocates n_elements elements, each one of size elem_sizes[i] Elements must be individually deallocated with deallocate() This function is available only with Version == 2

12.     void deallocate_many(multiallocation_chain & chain) noexcept;

    Deallocates several elements allocated by allocate_many(), allocate(), or allocation_command(). This function is available only with Version == 2

### `allocator` friend functions

1.     friend void swap(self_t &, self_t &) noexcept;

   Swaps two allocators, does nothing because this allocator is stateless

2.     friend bool operator==(const allocator &, const allocator &) noexcept;

   An allocator always compares to true, as memory allocated with one instance can be deallocated by another instance

3.     friend bool operator!=(const allocator &, const allocator &) noexcept;

   An allocator always compares to false, as memory allocated with one instance can be deallocated by another instance

### `allocator` private member functions

1.     pointer priv_allocation_command(allocation_type command,
                                       std::size_t limit_size,
                                       size_type & prefer_in_recvd_out_size,
                                       pointer & reuse_ptr);