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


Class synchronized_pool_resource



// In header: <boost/container/pmr/synchronized_pool_resource.hpp>

class synchronized_pool_resource :
  public boost::container::pmr::memory_resource
  // construct/copy/destruct
  synchronized_pool_resource(const pool_options &, memory_resource *) noexcept;
  synchronized_pool_resource() noexcept;
  explicit synchronized_pool_resource(memory_resource *) noexcept;
  explicit synchronized_pool_resource(const pool_options &) noexcept;
  synchronized_pool_resource(const synchronized_pool_resource &) = delete;
  operator=(const synchronized_pool_resource &) = delete;

  // public member functions
  void release();
  memory_resource * upstream_resource() const;
  pool_options options() const;
  std::size_t pool_count() const;
  std::size_t pool_index(std::size_t) const;
  std::size_t pool_next_blocks_per_chunk(std::size_t) const;
  std::size_t pool_block(std::size_t) const;
  std::size_t pool_cached_blocks(std::size_t) const;

  // protected member functions
  virtual void * do_allocate(std::size_t, std::size_t);
  virtual void do_deallocate(void *, std::size_t, std::size_t);
  virtual bool do_is_equal(const memory_resource &) const noexcept;


A synchronized_pool_resource is a general-purpose memory resources having the following qualities:

  • Each resource owns the allocated memory, and frees it on destruction, even if deallocate has not been called for some of the allocated blocks.

  • A pool resource consists of a collection of pools, serving requests for different block sizes. Each individual pool manages a collection of chunks that are in turn divided into blocks of uniform size, returned via calls to do_allocate. Each call to do_allocate(size, alignment) is dispatched to the pool serving the smallest blocks accommodating at least size bytes.

  • When a particular pool is exhausted, allocating a block from that pool results in the allocation of an additional chunk of memory from the upstream allocator (supplied at construction), thus replenishing the pool. With each successive replenishment, the chunk size obtained increases geometrically. [ Note: By allocating memory in chunks, the pooling strategy increases the chance that consecutive allocations will be close together in memory. - end note ]

  • Allocation requests that exceed the largest block size of any pool are fulfilled directly from the upstream allocator.

  • A pool_options struct may be passed to the pool resource constructors to tune the largest block size and the maximum chunk size.

A synchronized_pool_resource may be accessed from multiple threads without external synchronization and may have thread-specific pools to reduce synchronization costs.

synchronized_pool_resource public construct/copy/destruct

  1. synchronized_pool_resource(const pool_options & opts, 
                               memory_resource * upstream) noexcept;

    Requires: upstream is the address of a valid memory resource.

    Effects: Constructs a pool resource object that will obtain memory from upstream whenever the pool resource is unable to satisfy a memory request from its own internal data structures. The resulting object will hold a copy of upstream, but will not own the resource to which upstream points. [ Note: The intention is that calls to upstream->allocate() will be substantially fewer than calls to this->allocate() in most cases. - end note The behavior of the pooling mechanism is tuned according to the value of the opts argument.

    Throws: Nothing unless upstream->allocate() throws. It is unspecified if or under what conditions this constructor calls upstream->allocate().

  2. synchronized_pool_resource() noexcept;

    Effects: Same as unsynchronized_pool_resource(pool_options(), get_default_resource()).

  3. explicit synchronized_pool_resource(memory_resource * upstream) noexcept;

    Effects: Same as unsynchronized_pool_resource(pool_options(), upstream).

  4. explicit synchronized_pool_resource(const pool_options & opts) noexcept;

    Effects: Same as unsynchronized_pool_resource(opts, get_default_resource()).

  5. synchronized_pool_resource(const synchronized_pool_resource &) = delete;
  6. synchronized_pool_resource 
    operator=(const synchronized_pool_resource &) = delete;
  7. ~synchronized_pool_resource();

    Effects: Calls this->release().

synchronized_pool_resource public member functions

  1. void release();

    Effects: Calls Calls upstream_resource()->deallocate() as necessary to release all allocated memory. [ Note: memory is released back to upstream_resource() even if deallocate has not been called for some of the allocated blocks. - end note ]

  2. memory_resource * upstream_resource() const;

    Returns: The value of the upstream argument provided to the constructor of this object.

  3. pool_options options() const;

    Returns: The options that control the pooling behavior of this resource. The values in the returned struct may differ from those supplied to the pool resource constructor in that values of zero will be replaced with implementation-defined defaults and sizes may be rounded to unspecified granularity.

  4. std::size_t pool_count() const;

    Returns: The number of pools that will be used in the pool resource.

    Note: Non-standard extension.

  5. std::size_t pool_index(std::size_t bytes) const;

    Returns: The index of the pool that will be used to serve the allocation of bytes. Returns pool_count() if bytes is bigger than options().largest_required_pool_block (no pool will be used to serve this).

    Note: Non-standard extension.

  6. std::size_t pool_next_blocks_per_chunk(std::size_t pool_idx) const;

    Requires: pool_idx < pool_index()

    Returns: The number blocks that will be allocated in the next chunk from the pool specified by pool_idx.

    Note: Non-standard extension.

  7. std::size_t pool_block(std::size_t pool_idx) const;

    Requires: pool_idx < pool_index()

    Returns: The number of bytes of the block that the specified pool_idx pool manages.

    Note: Non-standard extension.

  8. std::size_t pool_cached_blocks(std::size_t pool_idx) const;

    Requires: pool_idx < pool_index()

    Returns: The number of blocks that the specified pool_idx pool has cached and will be served without calling the upstream_allocator.

    Note: Non-standard extension.

synchronized_pool_resource protected member functions

  1. virtual void * do_allocate(std::size_t bytes, std::size_t alignment);

    Returns: A pointer to allocated storage with a size of at least bytes. The size and alignment of the allocated memory shall meet the requirements for a class derived from memory_resource.

    Effects: If the pool selected for a block of size bytes is unable to satisfy the memory request from its own internal data structures, it will call upstream_resource()->allocate() to obtain more memory. If bytes is larger than that which the largest pool can handle, then memory will be allocated using upstream_resource()->allocate().

    Throws: Nothing unless upstream_resource()->allocate() throws.

  2. virtual void do_deallocate(void * p, std::size_t bytes, std::size_t alignment);

    Effects: Return the memory at p to the pool. It is unspecified if or under what circumstances this operation will result in a call to upstream_resource()->deallocate().

    Throws: Nothing.

  3. virtual bool do_is_equal(const memory_resource & other) const noexcept;

    Returns: this == dynamic_cast<const unsynchronized_pool_resource*>(&other).