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 a snapshot of the master branch, built from commit eb1c924777.
PrevUpHomeNext

Class template cached_adaptive_pool

boost::interprocess::cached_adaptive_pool

Synopsis

// In header: <boost/interprocess/allocators/cached_adaptive_pool.hpp>

template<typename T, typename SegmentManager, std::size_t NodesPerBlock, 
         std::size_t MaxFreeBlocks, unsigned char OverheadPercent> 
class cached_adaptive_pool {
public:
  // types
  typedef implementation_defined::segment_manager segment_manager;
  typedef segment_manager::void_pointer           void_pointer;   
  typedef implementation_defined::pointer         pointer;        
  typedef implementation_defined::const_pointer   const_pointer;  
  typedef T                                       value_type;     
  typedef unspecified                             reference;      
  typedef unspecified                             const_reference;
  typedef segment_manager::size_type              size_type;      
  typedef segment_manager::difference_type        difference_type;

  // member classes/structs/unions
  template<typename T2> 
  struct rebind {
    // types
    typedef cached_adaptive_pool< T2, SegmentManager, NodesPerBlock, MaxFreeBlocks, OverheadPercent > other;
  };

  // private member functions
  template<typename T2, typename SegmentManager2, std::size_t N2, 
           std::size_t F2, unsigned char OP2> 
    cached_adaptive_pool & 
    operator=(const cached_adaptive_pool< T2, SegmentManager2, N2, F2, OP2 > &);
  cached_adaptive_pool & operator=(const cached_adaptive_pool &);

  // public member functions
  cached_adaptive_pool(segment_manager *);
  cached_adaptive_pool(const cached_adaptive_pool &);
  template<typename T2> 
    cached_adaptive_pool(const cached_adaptive_pool< T2, SegmentManager, NodesPerBlock, MaxFreeBlocks, OverheadPercent > &);
  ~cached_adaptive_pool();
  node_pool_t * get_node_pool() const;
  segment_manager * get_segment_manager() const;
  size_type max_size() const;
  pointer allocate(size_type, cvoid_pointer = 0);
  void deallocate(const pointer &, size_type);
  void deallocate_free_blocks();
  pointer address(reference) const;
  const_pointer address(const_reference) const;
  void construct(const pointer &, const_reference);
  void destroy(const pointer &);
  size_type size(const pointer &) const;
  pointer allocation_command(boost::interprocess::allocation_type, size_type, 
                             size_type &, pointer &);
  void allocate_many(size_type, size_type, multiallocation_chain &);
  void allocate_many(const size_type *, size_type, multiallocation_chain &);
  void deallocate_many(multiallocation_chain &);
  pointer allocate_one();
  multiallocation_chain allocate_individual(size_type);
  void deallocate_one(const pointer &);
  void deallocate_individual(multiallocation_chain &);
  void set_max_cached_nodes(size_type);
  size_type get_max_cached_nodes() const;

  // friend functions
  void swap(self_t &, self_t &);
};

Description

An STL node allocator that uses a segment manager as memory source. The internal pointer type will of the same type (raw, smart) as "typename SegmentManager::void_pointer" type. This allows placing the allocator in shared memory, memory mapped-files, etc...

This node allocator shares a segregated storage between all instances of cached_adaptive_pool with equal sizeof(T) placed in the same memory segment. But also caches some nodes privately to avoid some synchronization overhead.

NodesPerBlock is the minimum number of nodes of nodes allocated at once when the allocator needs runs out of nodes. MaxFreeBlocks is the maximum number of totally free blocks that the adaptive node pool will hold. The rest of the totally free blocks will be deallocated with the segment manager.

OverheadPercent is the (approximated) maximum size overhead (1-20%) of the allocator: (memory usable for nodes / total memory allocated from the segment manager)

cached_adaptive_pool private member functions

  1. template<typename T2, typename SegmentManager2, std::size_t N2, 
             std::size_t F2, unsigned char OP2> 
      cached_adaptive_pool & 
      operator=(const cached_adaptive_pool< T2, SegmentManager2, N2, F2, OP2 > &);

    Not assignable from related cached_adaptive_pool

  2. cached_adaptive_pool & operator=(const cached_adaptive_pool &);

    Not assignable from other cached_adaptive_pool

cached_adaptive_pool public member functions

  1. cached_adaptive_pool(segment_manager * segment_mngr);

    Constructor from a segment manager. If not present, constructs a node pool. Increments the reference count of the associated node pool. Can throw boost::interprocess::bad_alloc

  2. cached_adaptive_pool(const cached_adaptive_pool & other);

    Copy constructor from other cached_adaptive_pool. Increments the reference count of the associated node pool. Never throws

  3. template<typename T2> 
      cached_adaptive_pool(const cached_adaptive_pool< T2, SegmentManager, NodesPerBlock, MaxFreeBlocks, OverheadPercent > & other);

    Copy constructor from related cached_adaptive_pool. If not present, constructs a node pool. Increments the reference count of the associated node pool. Can throw boost::interprocess::bad_alloc

  4. ~cached_adaptive_pool();

    Destructor, removes node_pool_t from memory if its reference count reaches to zero. Never throws

  5. node_pool_t * get_node_pool() const;

    Returns a pointer to the node pool. Never throws

  6. segment_manager * get_segment_manager() const;

    Returns the segment manager. Never throws

  7. size_type max_size() const;

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

  8. pointer allocate(size_type count, cvoid_pointer hint = 0);

    Allocate memory for an array of count elements. Throws boost::interprocess::bad_alloc if there is no enough memory

  9. void deallocate(const pointer & ptr, size_type count);

    Deallocate allocated memory. Never throws

  10. void deallocate_free_blocks();

    Deallocates all free blocks of the pool

  11. pointer address(reference value) const;

    Returns address of mutable object. Never throws

  12. const_pointer address(const_reference value) const;

    Returns address of non mutable object. Never throws

  13. void construct(const pointer & ptr, const_reference v);

    Copy construct an object. Throws if T's copy constructor throws

  14. void destroy(const pointer & ptr);

    Destroys object. Throws if object's destructor throws

  15. size_type size(const pointer & p) const;

    Returns maximum the number of objects the previously allocated memory pointed by p can hold. This size only works for memory allocated with allocate, allocation_command and allocate_many.

  16. pointer allocation_command(boost::interprocess::allocation_type command, 
                               size_type limit_size, 
                               size_type & prefer_in_recvd_out_size, 
                               pointer & reuse);
  17. void allocate_many(size_type elem_size, size_type num_elements, 
                       multiallocation_chain & chain);

    Allocates many elements of size elem_size in a contiguous block of memory. The minimum number to be allocated is min_elements, the preferred and maximum number is preferred_elements. The number of actually allocated elements is will be assigned to received_size. The elements must be deallocated with deallocate(...)

  18. 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]in a contiguous block of memory. The elements must be deallocated

  19. void deallocate_many(multiallocation_chain & chain);

    Allocates many elements of size elem_size in a contiguous block of memory. The minimum number to be allocated is min_elements, the preferred and maximum number is preferred_elements. The number of actually allocated elements is will be assigned to received_size. The elements must be deallocated with deallocate(...)

  20. pointer allocate_one();

    Allocates just one object. Memory allocated with this function must be deallocated only with deallocate_one(). Throws boost::interprocess::bad_alloc if there is no enough memory

  21. multiallocation_chain allocate_individual(size_type num_elements);

    Allocates many elements of size == 1 in a contiguous block of memory. The minimum number to be allocated is min_elements, the preferred and maximum number is preferred_elements. The number of actually allocated elements is will be assigned to received_size. Memory allocated with this function must be deallocated only with deallocate_one().

  22. void deallocate_one(const pointer & p);

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

  23. void deallocate_individual(multiallocation_chain & chain);

    Allocates many elements of size == 1 in a contiguous block of memory. The minimum number to be allocated is min_elements, the preferred and maximum number is preferred_elements. The number of actually allocated elements is will be assigned to received_size. Memory allocated with this function must be deallocated only with deallocate_one().

  24. void set_max_cached_nodes(size_type newmax);

    Sets the new max cached nodes value. This can provoke deallocations if "newmax" is less than current cached nodes. Never throws

  25. size_type get_max_cached_nodes() const;

    Returns the max cached nodes parameter. Never throws

cached_adaptive_pool friend functions

  1. void swap(self_t & alloc1, self_t & alloc2);

    Swaps allocators. Does not throw. If each allocator is placed in a different memory segment, the result is undefined.


PrevUpHomeNext