ceph/src/boost/boost/container/pmr/unsynchronized_pool_resource.hpp

   1 //////////////////////////////////////////////////////////////////////////////
   2 //
   3 // (C) Copyright Ion Gaztanaga 2015-2015. Distributed under the Boost
   4 // Software License, Version 1.0. (See accompanying file
   5 // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6 //
   7 // See http://www.boost.org/libs/container for documentation.
   8 //
   9 //////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef BOOST_CONTAINER_PMR_UNSYNCHRONIZED_POOL_RESOURCE_HPP
  12 #define BOOST_CONTAINER_PMR_UNSYNCHRONIZED_POOL_RESOURCE_HPP
  13
  14 #if defined (_MSC_VER)
  15 #  pragma once
  16 #endif
  17
  18 #include <boost/container/detail/config_begin.hpp>
  19 #include <boost/container/detail/workaround.hpp>
  20 #include <boost/container/detail/auto_link.hpp>
  21 #include <boost/container/pmr/memory_resource.hpp>
  22 #include <boost/container/detail/pool_resource.hpp>
  23
  24 #include <cstddef>
  25
  26 namespace boost {
  27 namespace container {
  28 namespace pmr {
  29
  30 //! A unsynchronized_pool_resource is a general-purpose memory resources having
  31 //! the following qualities:
  32 //!
  33 //! - Each resource owns the allocated memory, and frees it on destruction,
  34 //!   even if deallocate has not been called for some of the allocated blocks.
  35 //!
  36 //! - A pool resource consists of a collection of pools, serving
  37 //!   requests for different block sizes. Each individual pool manages a
  38 //!   collection of chunks that are in turn divided into blocks of uniform size,
  39 //!   returned via calls to do_allocate. Each call to do_allocate(size, alignment)
  40 //!   is dispatched to the pool serving the smallest blocks accommodating at
  41 //!   least size bytes.
  42 //!
  43 //! - When a particular pool is exhausted, allocating a block from that pool
  44 //!   results in the allocation of an additional chunk of memory from the upstream
  45 //!   allocator (supplied at construction), thus replenishing the pool. With
  46 //!   each successive replenishment, the chunk size obtained increases
  47 //!   geometrically. [ Note: By allocating memory in chunks, the pooling strategy
  48 //!   increases the chance that consecutive allocations will be close together
  49 //!   in memory. - end note ]
  50 //!
  51 //! - Allocation requests that exceed the largest block size of any pool are
  52 //!   fulfilled directly from the upstream allocator.
  53 //!
  54 //! - A pool_options struct may be passed to the pool resource constructors to
  55 //!   tune the largest block size and the maximum chunk size.
  56 //!
  57 //! An unsynchronized_pool_resource class may not be accessed from multiple threads
  58 //! simultaneously and thus avoids the cost of synchronization entirely in
  59 //! single-threaded applications.
  60 class BOOST_CONTAINER_DECL unsynchronized_pool_resource
  61    : public memory_resource
  62 {
  63    pool_resource m_resource;
  64
  65    public:
  66
  67    //! <b>Requires</b>: `upstream` is the address of a valid memory resource.
  68    //!
  69    //! <b>Effects</b>: Constructs a pool resource object that will obtain memory
  70    //!   from upstream whenever the pool resource is unable to satisfy a memory
  71    //!   request from its own internal data structures. The resulting object will hold
  72    //!   a copy of upstream, but will not own the resource to which upstream points.
  73    //!   [ Note: The intention is that calls to upstream->allocate() will be
  74    //!   substantially fewer than calls to this->allocate() in most cases. - end note
  75    //!   The behavior of the pooling mechanism is tuned according to the value of
  76    //!   the opts argument.
  77    //!
  78    //! <b>Throws</b>: Nothing unless upstream->allocate() throws. It is unspecified if
  79    //!   or under what conditions this constructor calls upstream->allocate().
  80    unsynchronized_pool_resource(const pool_options& opts, memory_resource* upstream) BOOST_NOEXCEPT;
  81
  82    //! <b>Effects</b>: Same as
  83    //!   `unsynchronized_pool_resource(pool_options(), get_default_resource())`.
  84    unsynchronized_pool_resource() BOOST_NOEXCEPT;
  85
  86    //! <b>Effects</b>: Same as
  87    //!   `unsynchronized_pool_resource(pool_options(), upstream)`.
  88    explicit unsynchronized_pool_resource(memory_resource* upstream) BOOST_NOEXCEPT;
  89
  90    //! <b>Effects</b>: Same as
  91    //!   `unsynchronized_pool_resource(opts, get_default_resource())`.
  92    explicit unsynchronized_pool_resource(const pool_options& opts) BOOST_NOEXCEPT;
  93
  94    #if !defined(BOOST_NO_CXX11_DELETED_FUNCTIONS) || defined(BOOST_CONTAINER_DOXYGEN_INVOKED)
  95    unsynchronized_pool_resource(const unsynchronized_pool_resource&) = delete;
  96    unsynchronized_pool_resource operator=(const unsynchronized_pool_resource&) = delete;
  97    #else
  98    private:
  99    unsynchronized_pool_resource          (const unsynchronized_pool_resource&);
 100    unsynchronized_pool_resource operator=(const unsynchronized_pool_resource&);
 101    public:
 102    #endif
 103
 104    //! <b>Effects</b>: Calls
 105    //!   `this->release()`.
 106    ~unsynchronized_pool_resource() BOOST_OVERRIDE;
 107
 108    //! <b>Effects</b>: Calls Calls `upstream_resource()->deallocate()` as necessary
 109    //!   to release all allocated memory. [ Note: memory is released back to
 110    //!   `upstream_resource()` even if deallocate has not been called for some
 111    //!   of the allocated blocks. - end note ]
 112    void release();
 113
 114    //! <b>Returns</b>: The value of the upstream argument provided to the
 115    //!   constructor of this object.
 116    memory_resource* upstream_resource() const;
 117
 118    //! <b>Returns</b>: The options that control the pooling behavior of this resource.
 119    //!   The values in the returned struct may differ from those supplied to the pool
 120    //!   resource constructor in that values of zero will be replaced with
 121    //!   implementation-defined defaults and sizes may be rounded to unspecified granularity.
 122    pool_options options() const;
 123
 124    protected:
 125
 126    //! <b>Returns</b>: A pointer to allocated storage with a size of at least `bytes`.
 127    //!   The size and alignment of the allocated memory shall meet the requirements for
 128    //!   a class derived from `memory_resource`.
 129    //!
 130    //! <b>Effects</b>: If the pool selected for a block of size bytes is unable to
 131    //!   satisfy the memory request from its own internal data structures, it will call
 132    //!   `upstream_resource()->allocate()` to obtain more memory. If `bytes` is larger
 133    //!   than that which the largest pool can handle, then memory will be allocated
 134    //!   using `upstream_resource()->allocate()`.
 135    //!
 136    //! <b>Throws</b>: Nothing unless `upstream_resource()->allocate()` throws.
 137    void* do_allocate(std::size_t bytes, std::size_t alignment) BOOST_OVERRIDE;
 138
 139    //! <b>Effects</b>: Return the memory at p to the pool. It is unspecified if or under
 140    //!   what circumstances this operation will result in a call to
 141    //!   `upstream_resource()->deallocate()`.
 142    //!
 143    //! <b>Throws</b>: Nothing.
 144    void do_deallocate(void* p, std::size_t bytes, std::size_t alignment) BOOST_OVERRIDE;
 145
 146    //! <b>Returns</b>:
 147    //!   `this == dynamic_cast<const unsynchronized_pool_resource*>(&other)`.
 148    bool do_is_equal(const memory_resource& other) const BOOST_NOEXCEPT BOOST_OVERRIDE;
 149
 150    //Non-standard observers
 151    public:
 152    //! <b>Returns</b>: The number of pools that will be used in the pool resource.
 153    //!
 154    //! <b>Note</b>: Non-standard extension.
 155    std::size_t pool_count() const;
 156
 157    //! <b>Returns</b>: The index of the pool that will be used to serve the allocation of `bytes`.
 158    //!   Returns `pool_count()` if `bytes` is bigger
 159    //!   than `options().largest_required_pool_block` (no pool will be used to serve this).
 160    //!
 161    //! <b>Note</b>: Non-standard extension.
 162    std::size_t pool_index(std::size_t bytes) const;
 163
 164    //! <b>Requires</b>: `pool_idx < pool_index()`
 165    //!
 166    //! <b>Returns</b>: The number blocks that will be allocated in the next chunk
 167    //!   from the pool specified by `pool_idx`.
 168    //!
 169    //! <b>Note</b>: Non-standard extension.
 170    std::size_t pool_next_blocks_per_chunk(std::size_t pool_idx) const;
 171
 172    //! <b>Requires</b>: `pool_idx < pool_index()`
 173    //!
 174    //! <b>Returns</b>: The number of bytes of the block that the specified `pool_idx` pool manages.
 175    //!
 176    //! <b>Note</b>: Non-standard extension.
 177    std::size_t pool_block(std::size_t pool_idx) const;
 178
 179    //! <b>Requires</b>: `pool_idx < pool_index()`
 180    //!
 181    //! <b>Returns</b>: The number of blocks that the specified `pool_idx` pool has cached
 182    //!   and will be served without calling the upstream_allocator.
 183    //!
 184    //! <b>Note</b>: Non-standard extension.
 185    std::size_t pool_cached_blocks(std::size_t pool_idx) const;
 186 };
 187
 188 }  //namespace pmr {
 189 }  //namespace container {
 190 }  //namespace boost {
 191
 192 #include <boost/container/detail/config_end.hpp>
 193
 194 #endif   //BOOST_CONTAINER_PMR_UNSYNCHRONIZED_POOL_RESOURCE_HPP