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 195