libstdc++
memory_resource
Go to the documentation of this file.
1// <memory_resource> -*- C++ -*-
2
3// Copyright (C) 2018-2024 Free Software Foundation, Inc.
4//
5// This file is part of the GNU ISO C++ Library. This library is free
6// software; you can redistribute it and/or modify it under the
7// terms of the GNU General Public License as published by the
8// Free Software Foundation; either version 3, or (at your option)
9// any later version.
10
11// This library is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// Under Section 7 of GPL version 3, you are granted additional
17// permissions described in the GCC Runtime Library Exception, version
18// 3.1, as published by the Free Software Foundation.
19
20// You should have received a copy of the GNU General Public License and
21// a copy of the GCC Runtime Library Exception along with this program;
22// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23// <http://www.gnu.org/licenses/>.
24
25/** @file include/memory_resource
26 * This is a Standard C++ Library header.
27 *
28 * This header declares the @ref pmr (std::pmr) memory resources.
29 * @ingroup pmr
30 */
31
32#ifndef _GLIBCXX_MEMORY_RESOURCE
33#define _GLIBCXX_MEMORY_RESOURCE 1
34
35#pragma GCC system_header
36
37#include <bits/requires_hosted.h> // polymorphic allocation
38
39#define __glibcxx_want_polymorphic_allocator
40#define __glibcxx_want_memory_resource
41#include <bits/version.h>
42
43#if __cplusplus >= 201703L
44
45/**
46 * @defgroup pmr Polymorphic memory resources
47 *
48 * @anchor pmr
49 * @ingroup memory
50 * @since C++17
51 *
52 * Memory resources are classes that implement the `std::pmr::memory_resource`
53 * interface for allocating and deallocating memory. Unlike traditional C++
54 * allocators, memory resources are not value types and are used via pointers
55 * to the abstract base class. They are only responsible for allocating and
56 * deallocating, not for construction and destruction of objects. As a result,
57 * memory resources just allocate raw memory as type `void*` and are not
58 * templates that allocate/deallocate and construct/destroy a specific type.
59 *
60 * The class template `std::pmr::polymorphic_allocator` is an allocator that
61 * uses a memory resource for its allocations.
62 */
63
64#include <bits/memory_resource.h>
65#include <vector> // vector
66#include <shared_mutex> // shared_mutex
67#include <bits/align.h> // align
68#include <debug/assertions.h>
69
70namespace std _GLIBCXX_VISIBILITY(default)
71{
72_GLIBCXX_BEGIN_NAMESPACE_VERSION
73namespace pmr
74{
75
76#ifdef __cpp_lib_polymorphic_allocator // C++ >= 20 && HOSTED
77 template<typename _Tp = std::byte>
78 class polymorphic_allocator;
79#endif
80
81 // Global memory resources
82
83 /// A pmr::memory_resource that uses `new` to allocate memory
84 /**
85 * @ingroup pmr
86 * @headerfile memory_resource
87 * @since C++17
88 */
89 [[nodiscard, __gnu__::__returns_nonnull__, __gnu__::__const__]]
90 memory_resource*
91 new_delete_resource() noexcept;
92
93 /// A pmr::memory_resource that always throws `bad_alloc`
94 [[nodiscard, __gnu__::__returns_nonnull__, __gnu__::__const__]]
95 memory_resource*
96 null_memory_resource() noexcept;
97
98 /// Replace the default memory resource pointer
99 [[__gnu__::__returns_nonnull__]]
100 memory_resource*
101 set_default_resource(memory_resource* __r) noexcept;
102
103 /// Get the current default memory resource pointer
104 [[__gnu__::__returns_nonnull__]]
105 memory_resource*
106 get_default_resource() noexcept;
107
108 // Pool resource classes
109 struct pool_options;
110#if __cpp_lib_memory_resource >= 201603L // C++ >= 17 && hosted && gthread
111 class synchronized_pool_resource;
112#endif
113 class unsynchronized_pool_resource;
114 class monotonic_buffer_resource;
115
116 /// Parameters for tuning a pool resource's behaviour.
117 /**
118 * @ingroup pmr
119 * @headerfile memory_resource
120 * @since C++17
121 */
122 struct pool_options
123 {
124 /** @brief Upper limit on number of blocks in a chunk.
125 *
126 * A lower value prevents allocating huge chunks that could remain mostly
127 * unused, but means pools will need to replenished more frequently.
128 */
129 size_t max_blocks_per_chunk = 0;
130
131 /* @brief Largest block size (in bytes) that should be served from pools.
132 *
133 * Larger allocations will be served directly by the upstream resource,
134 * not from one of the pools managed by the pool resource.
135 */
136 size_t largest_required_pool_block = 0;
137 };
138
139 // Common implementation details for un-/synchronized pool resources.
140 class __pool_resource
141 {
142 friend class synchronized_pool_resource;
143 friend class unsynchronized_pool_resource;
144
145 __pool_resource(const pool_options& __opts, memory_resource* __upstream);
146
147 ~__pool_resource();
148
149 __pool_resource(const __pool_resource&) = delete;
150 __pool_resource& operator=(const __pool_resource&) = delete;
151
152 // Allocate a large unpooled block.
153 void*
154 allocate(size_t __bytes, size_t __alignment);
155
156 // Deallocate a large unpooled block.
157 void
158 deallocate(void* __p, size_t __bytes, size_t __alignment);
159
160
161 // Deallocate unpooled memory.
162 void release() noexcept;
163
164 memory_resource* resource() const noexcept
165 { return _M_unpooled.get_allocator().resource(); }
166
167 struct _Pool;
168
169 _Pool* _M_alloc_pools();
170
171 const pool_options _M_opts;
172
173 struct _BigBlock;
174 // Collection of blocks too big for any pool, sorted by address.
175 // This also stores the only copy of the upstream memory resource pointer.
176 _GLIBCXX_STD_C::pmr::vector<_BigBlock> _M_unpooled;
177
178 const int _M_npools;
179 };
180
181#if __cpp_lib_memory_resource >= 201603L // C++ >= 17 && hosted && gthread
182 /// A thread-safe memory resource that manages pools of fixed-size blocks.
183 /**
184 * @ingroup pmr
185 * @headerfile memory_resource
186 * @since C++17
187 */
188 class synchronized_pool_resource : public memory_resource
189 {
190 public:
191 synchronized_pool_resource(const pool_options& __opts,
192 memory_resource* __upstream)
193 __attribute__((__nonnull__));
194
195 synchronized_pool_resource()
196 : synchronized_pool_resource(pool_options(), get_default_resource())
197 { }
198
199 explicit
200 synchronized_pool_resource(memory_resource* __upstream)
201 __attribute__((__nonnull__))
202 : synchronized_pool_resource(pool_options(), __upstream)
203 { }
204
205 explicit
206 synchronized_pool_resource(const pool_options& __opts)
207 : synchronized_pool_resource(__opts, get_default_resource()) { }
208
209 synchronized_pool_resource(const synchronized_pool_resource&) = delete;
210
211 virtual ~synchronized_pool_resource();
212
213 synchronized_pool_resource&
214 operator=(const synchronized_pool_resource&) = delete;
215
216 void release();
217
218 memory_resource*
219 upstream_resource() const noexcept
220 __attribute__((__returns_nonnull__))
221 { return _M_impl.resource(); }
222
223 pool_options options() const noexcept { return _M_impl._M_opts; }
224
225 protected:
226 void*
227 do_allocate(size_t __bytes, size_t __alignment) override;
228
229 void
230 do_deallocate(void* __p, size_t __bytes, size_t __alignment) override;
231
232 bool
233 do_is_equal(const memory_resource& __other) const noexcept override
234 { return this == &__other; }
235
236 public:
237 // Thread-specific pools (only public for access by implementation details)
238 struct _TPools;
239
240 private:
241 _TPools* _M_alloc_tpools(lock_guard<shared_mutex>&);
242 _TPools* _M_alloc_shared_tpools(lock_guard<shared_mutex>&);
243 auto _M_thread_specific_pools() noexcept;
244
245 __pool_resource _M_impl;
246 __gthread_key_t _M_key;
247 // Linked list of thread-specific pools. All threads share _M_tpools[0].
248 _TPools* _M_tpools = nullptr;
249 mutable shared_mutex _M_mx;
250 };
251#endif // __cpp_lib_memory_resource >= 201603L
252
253 /// A non-thread-safe memory resource that manages pools of fixed-size blocks.
254 /**
255 * @ingroup pmr
256 * @headerfile memory_resource
257 * @since C++17
258 */
259 class unsynchronized_pool_resource : public memory_resource
260 {
261 public:
262 [[__gnu__::__nonnull__]]
263 unsynchronized_pool_resource(const pool_options& __opts,
264 memory_resource* __upstream);
265
266 unsynchronized_pool_resource()
267 : unsynchronized_pool_resource(pool_options(), get_default_resource())
268 { }
269
270 [[__gnu__::__nonnull__]]
271 explicit
272 unsynchronized_pool_resource(memory_resource* __upstream)
273 : unsynchronized_pool_resource(pool_options(), __upstream)
274 { }
275
276 explicit
277 unsynchronized_pool_resource(const pool_options& __opts)
278 : unsynchronized_pool_resource(__opts, get_default_resource()) { }
279
280 unsynchronized_pool_resource(const unsynchronized_pool_resource&) = delete;
281
282 virtual ~unsynchronized_pool_resource();
283
284 unsynchronized_pool_resource&
285 operator=(const unsynchronized_pool_resource&) = delete;
286
287 void release();
288
289 [[__gnu__::__returns_nonnull__]]
290 memory_resource*
291 upstream_resource() const noexcept
292 { return _M_impl.resource(); }
293
294 pool_options options() const noexcept { return _M_impl._M_opts; }
295
296 protected:
297 void*
298 do_allocate(size_t __bytes, size_t __alignment) override;
299
300 void
301 do_deallocate(void* __p, size_t __bytes, size_t __alignment) override;
302
303 bool
304 do_is_equal(const memory_resource& __other) const noexcept override
305 { return this == &__other; }
306
307 private:
308 using _Pool = __pool_resource::_Pool;
309
310 auto _M_find_pool(size_t) noexcept;
311
312 __pool_resource _M_impl;
313 _Pool* _M_pools = nullptr;
314 };
315
316 /// A memory resource that allocates from a fixed-size buffer.
317 /**
318 * The main feature of a `pmr::monotonic_buffer_resource` is that its
319 * `do_deallocate` does nothing. This makes it very fast because there is no
320 * need to manage a free list, and every allocation simply returns a new
321 * block of memory, rather than searching for a suitably-sized free block.
322 * Because deallocating is a no-op, the amount of memory used by the resource
323 * only grows until `release()` (or the destructor) is called to return all
324 * memory to upstream.
325 *
326 * A `monotonic_buffer_resource` can be initialized with a buffer that
327 * will be used to satisfy all allocation requests, until the buffer is full.
328 * After that a new buffer will be allocated from the upstream resource.
329 * By using a stack buffer and `pmr::null_memory_resource()` as the upstream
330 * you can get a memory resource that only uses the stack and never
331 * dynamically allocates.
332 *
333 * @ingroup pmr
334 * @headerfile memory_resource
335 * @since C++17
336 */
337 class monotonic_buffer_resource : public memory_resource
338 {
339 public:
340 explicit
341 monotonic_buffer_resource(memory_resource* __upstream) noexcept
342 __attribute__((__nonnull__))
343 : _M_upstream(__upstream)
344 { _GLIBCXX_DEBUG_ASSERT(__upstream != nullptr); }
345
346 monotonic_buffer_resource(size_t __initial_size,
347 memory_resource* __upstream) noexcept
348 __attribute__((__nonnull__))
349 : _M_next_bufsiz(__initial_size),
350 _M_upstream(__upstream)
351 {
352 _GLIBCXX_DEBUG_ASSERT(__upstream != nullptr);
353 _GLIBCXX_DEBUG_ASSERT(__initial_size > 0);
354 }
355
356 monotonic_buffer_resource(void* __buffer, size_t __buffer_size,
357 memory_resource* __upstream) noexcept
358 __attribute__((__nonnull__(4)))
359 : _M_current_buf(__buffer), _M_avail(__buffer_size),
360 _M_next_bufsiz(_S_next_bufsize(__buffer_size)),
361 _M_upstream(__upstream),
362 _M_orig_buf(__buffer), _M_orig_size(__buffer_size)
363 {
364 _GLIBCXX_DEBUG_ASSERT(__upstream != nullptr);
365 _GLIBCXX_DEBUG_ASSERT(__buffer != nullptr || __buffer_size == 0);
366 }
367
368 monotonic_buffer_resource() noexcept
369 : monotonic_buffer_resource(get_default_resource())
370 { }
371
372 explicit
373 monotonic_buffer_resource(size_t __initial_size) noexcept
374 : monotonic_buffer_resource(__initial_size, get_default_resource())
375 { }
376
377 monotonic_buffer_resource(void* __buffer, size_t __buffer_size) noexcept
378 : monotonic_buffer_resource(__buffer, __buffer_size, get_default_resource())
379 { }
380
381 monotonic_buffer_resource(const monotonic_buffer_resource&) = delete;
382
383 virtual ~monotonic_buffer_resource(); // key function
384
385 monotonic_buffer_resource&
386 operator=(const monotonic_buffer_resource&) = delete;
387
388 void
389 release() noexcept
390 {
391 if (_M_head)
392 _M_release_buffers();
393
394 // reset to initial state at contruction:
395 if ((_M_current_buf = _M_orig_buf))
396 {
397 _M_avail = _M_orig_size;
398 _M_next_bufsiz = _S_next_bufsize(_M_orig_size);
399 }
400 else
401 {
402 _M_avail = 0;
403 _M_next_bufsiz = _M_orig_size;
404 }
405 }
406
407 memory_resource*
408 upstream_resource() const noexcept
409 __attribute__((__returns_nonnull__))
410 { return _M_upstream; }
411
412 protected:
413 void*
414 do_allocate(size_t __bytes, size_t __alignment) override
415 {
416 if (__builtin_expect(__bytes == 0, false))
417 __bytes = 1; // Ensures we don't return the same pointer twice.
418
419 void* __p = std::align(__alignment, __bytes, _M_current_buf, _M_avail);
420 if (__builtin_expect(__p == nullptr, false))
421 {
422 _M_new_buffer(__bytes, __alignment);
423 __p = _M_current_buf;
424 }
425 _M_current_buf = (char*)_M_current_buf + __bytes;
426 _M_avail -= __bytes;
427 return __p;
428 }
429
430 void
431 do_deallocate(void*, size_t, size_t) override
432 { }
433
434 bool
435 do_is_equal(const memory_resource& __other) const noexcept override
436 { return this == &__other; }
437
438 private:
439 // Update _M_current_buf and _M_avail to refer to a new buffer with
440 // at least the specified size and alignment, allocated from upstream.
441 void
442 _M_new_buffer(size_t __bytes, size_t __alignment);
443
444 // Deallocate all buffers obtained from upstream.
445 void
446 _M_release_buffers() noexcept;
447
448 static size_t
449 _S_next_bufsize(size_t __buffer_size) noexcept
450 {
451 if (__builtin_expect(__buffer_size == 0, false))
452 __buffer_size = 1;
453 return __buffer_size * _S_growth_factor;
454 }
455
456 static constexpr size_t _S_init_bufsize = 128 * sizeof(void*);
457 static constexpr float _S_growth_factor = 1.5;
458
459 void* _M_current_buf = nullptr;
460 size_t _M_avail = 0;
461 size_t _M_next_bufsiz = _S_init_bufsize;
462
463 // Initial values set at construction and reused by release():
464 memory_resource* const _M_upstream;
465 void* const _M_orig_buf = nullptr;
466 size_t const _M_orig_size = _M_next_bufsiz;
467
468 class _Chunk;
469 _Chunk* _M_head = nullptr;
470 };
471
472} // namespace pmr
473_GLIBCXX_END_NAMESPACE_VERSION
474} // namespace std
475
476#endif // C++17
477#endif // _GLIBCXX_MEMORY_RESOURCE