Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
PrevUpHomeNext

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 boost::container::dtl::version_type< self_t, Version > 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 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);

PrevUpHomeNext