MySQL  8.0.16
Source Code Documentation
my_alloc.h
Go to the documentation of this file.
1 /* Copyright (c) 2000, 2018, Oracle and/or its affiliates. All rights reserved.
2 
3  This program is free software; you can redistribute it and/or modify
4  it under the terms of the GNU General Public License, version 2.0,
5  as published by the Free Software Foundation.
6 
7  This program is also distributed with certain software (including
8  but not limited to OpenSSL) that is licensed under separate terms,
9  as designated in a particular file or component or in included license
10  documentation. The authors of MySQL hereby grant you an additional
11  permission to link the program and your derivative works with the
12  separately licensed software that they have included with MySQL.
13 
14  This program is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License, version 2.0, for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with this program; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 /**
24  * @file include/my_alloc.h
25  *
26  * This file follows Google coding style, except for the name MEM_ROOT (which is
27  * kept for historical reasons).
28  */
29 
30 #ifndef INCLUDE_MY_ALLOC_H_
31 #define INCLUDE_MY_ALLOC_H_
32 
33 #include <string.h>
34 
35 #include <memory>
36 #include <new>
37 #include <type_traits>
38 #include <utility>
39 
40 #include "my_compiler.h"
41 #include "my_dbug.h"
42 #include "my_inttypes.h"
43 #include "my_pointer_arithmetic.h"
44 #include "mysql/psi/psi_memory.h"
45 
46 /**
47  * The MEM_ROOT is a simple arena, where allocations are carved out of
48  * larger blocks. Using an arena over plain malloc gives you two main
49  * advantages:
50  *
51  * * Allocation is very cheap (only a few CPU cycles on the fast path).
52  * * You do not need to keep track of which memory you have allocated,
53  * as it will all be freed when the arena is destroyed.
54  *
55  * Thus, if you need to do many small allocations that all are to have
56  * roughly the same lifetime, the MEM_ROOT is probably a good choice.
57  * The flip side is that _no_ memory is freed until the arena is destroyed,
58  * and no destructors are run (although you can run them manually yourself).
59  *
60  *
61  * This specific implementation works by allocating exponentially larger blocks
62  * each time it needs more memory (generally increasing them by 50%), which
63  * guarantees O(1) total calls to malloc and free. Only one free block is
64  * ever used; as soon as there's an allocation that comes in that doesn't fit,
65  * that block is stored away and never allocated from again. (There's an
66  * exception for allocations larger than the block size; see #AllocSlow
67  * for details.)
68  *
69  * The MEM_ROOT is thread-compatible but not thread-safe. This means you cannot
70  * use the same instance from multiple threads at the same time without external
71  * synchronization, but you can use different MEM_ROOTs concurrently in
72  * different threads.
73  *
74  * For C compatibility reasons, MEM_ROOT is a struct, even though it is
75  * logically a class and follows the style guide for classes.
76  */
77 struct MEM_ROOT {
78  private:
79  struct Block {
80  Block *prev{nullptr}; /** Previous block; used for freeing. */
81  };
82 
83  public:
84  MEM_ROOT() : MEM_ROOT(0, 512) {} // 0 = PSI_NOT_INSTRUMENTED.
85 
86  MEM_ROOT(PSI_memory_key key, size_t block_size)
87  : m_block_size(block_size),
88  m_orig_block_size(block_size),
89  m_psi_key(key) {}
90 
91  // MEM_ROOT is movable but not copyable.
92  MEM_ROOT(const MEM_ROOT &) = delete;
93  MEM_ROOT(MEM_ROOT &&other)
94  noexcept
95  : m_current_block(other.m_current_block),
96  m_current_free_start(other.m_current_free_start),
97  m_current_free_end(other.m_current_free_end),
98  m_block_size(other.m_block_size),
99  m_orig_block_size(other.m_orig_block_size),
100  m_max_capacity(other.m_max_capacity),
101  m_allocated_size(other.m_allocated_size),
102  m_error_for_capacity_exceeded(other.m_error_for_capacity_exceeded),
103  m_error_handler(other.m_error_handler),
104  m_psi_key(other.m_psi_key) {
105  other.m_current_block = nullptr;
106  other.m_allocated_size = 0;
107  other.m_block_size = m_orig_block_size;
108  other.m_current_free_start = &s_dummy_target;
109  other.m_current_free_end = &s_dummy_target;
110  }
111 
112  MEM_ROOT &operator=(const MEM_ROOT &) = delete;
113  MEM_ROOT &operator=(MEM_ROOT &&other) noexcept {
114  Clear();
115  ::new (this) MEM_ROOT(std::move(other));
116  return *this;
117  }
118 
119  ~MEM_ROOT() { Clear(); }
120 
121  /**
122  * Allocate memory. Will return nullptr if there's not enough memory,
123  * or if the maximum capacity is reached.
124  *
125  * Note that a zero-length allocation can return _any_ pointer, including
126  * nullptr or a pointer that has been given out before. The current
127  * implementation takes some pains to make sure we never return nullptr
128  * (although it might return a bogus pointer), since there is code that
129  * assumes nullptr always means “out of memory”, but you should not rely on
130  * it, as it may change in the future.
131  *
132  * The returned pointer will always be 8-aligned.
133  */
134  void *Alloc(size_t length) MY_ATTRIBUTE((malloc)) {
136 
137  // Skip the straight path if simulating OOM; it should always fail.
138  DBUG_EXECUTE_IF("simulate_out_of_memory", return AllocSlow(length););
139 
140  // Fast path, used in the majority of cases. It would be faster here
141  // (saving one register due to CSE) to instead test
142  //
143  // m_current_free_start + length <= m_current_free_end
144  //
145  // but it would invoke undefined behavior, and in particular be prone
146  // to wraparound on 32-bit platforms.
147  if (static_cast<size_t>(m_current_free_end - m_current_free_start) >=
148  length) {
149  void *ret = m_current_free_start;
151  return ret;
152  }
153 
154  return AllocSlow(length);
155  }
156 
157  /**
158  * Claim all the allocated memory for the current thread in the performance
159  * schema. Use when transferring responsibility for a MEM_ROOT from one thread
160  * to another.
161  */
162  void Claim();
163 
164  /**
165  * Deallocate all the RAM used. The MEM_ROOT itself continues to be valid,
166  * so you can make new calls to Alloc() afterwards.
167 
168  * @note
169  * One can call this function either with a MEM_ROOT initialized with the
170  * constructor, or with one that's memset() to all zeros.
171  * It's also safe to call this multiple times with the same mem_root.
172  */
173  void Clear();
174 
175  /**
176  * Similar to Clear(), but anticipates that the block will be reused for
177  * further allocations. This means that even though all the data is gone,
178  * one memory block (typically the largest allocated) will be kept and
179  * made immediately available for calls to Alloc() without having to go to the
180  * OS for new memory. This can yield performance gains if you use the same
181  * MEM_ROOT many times. Also, the block size is not reset.
182  */
183  void ClearForReuse();
184 
185  /**
186  Whether the constructor has run or not.
187 
188  This exists solely to support legacy code that memset()s the MEM_ROOT to
189  all zeros, which wants to distinguish between that state and a properly
190  initialized MEM_ROOT. If you do not run the constructor _nor_ do memset(),
191  you are invoking undefined behavior.
192  */
193  bool inited() const { return m_block_size != 0; }
194 
195  /**
196  * Set maximum capacity for this MEM_ROOT. Whenever the MEM_ROOT has
197  * allocated more than this (not including overhead), and the free block
198  * is empty, future allocations will fail.
199  *
200  * @param max_capacity Maximum capacity this mem_root can hold
201  */
202  void set_max_capacity(size_t max_capacity) { m_max_capacity = max_capacity; }
203 
204  /**
205  * Return maximum capacity for this MEM_ROOT.
206  */
207  size_t get_max_capacity() const { return m_max_capacity; }
208 
209  /**
210  * Enable/disable error reporting for exceeding the maximum capacity.
211  * If error reporting is enabled, an error is flagged to indicate that the
212  * capacity is exceeded. However, allocation will still happen for the
213  * requested memory.
214  *
215  * @param report_error whether the error should be reported
216  */
219  }
220 
221  /**
222  * Return whether error is to be reported when
223  * maximum capacity exceeds for MEM_ROOT.
224  */
227  }
228 
229  /**
230  * Set the error handler on memory allocation failure (or nullptr for none).
231  * The error handler is called called whenever my_malloc() failed to allocate
232  * more memory from the OS (which causes my_alloc() to return nullptr).
233  */
234  void set_error_handler(void (*error_handler)(void)) {
235  m_error_handler = error_handler;
236  }
237 
238  /**
239  * Amount of memory we have allocated from the operating system, not including
240  * overhead.
241  */
242  size_t allocated_size() const { return m_allocated_size; }
243 
244  /**
245  * Set the desired size of the next block to be allocated. Note that future
246  * allocations
247  * will grow in size over this, although a Clear() will reset the size again.
248  */
249  void set_block_size(size_t block_size) {
250  m_block_size = m_orig_block_size = block_size;
251  }
252 
253  private:
254  /**
255  * Something to point on that exists solely to never return nullptr
256  * from Alloc(0).
257  */
258  static char s_dummy_target;
259 
260  /**
261  Allocate a new block of the given length (plus overhead for the block
262  header).
263  */
264  Block *AllocBlock(size_t length);
265 
266  /** Allocate memory that doesn't fit into the current free block. */
267  void *AllocSlow(size_t length);
268 
269  /** Free all blocks in a linked list, starting at the given block. */
270  static void FreeBlocks(Block *start);
271 
272  /** The current block we are giving out memory from. nullptr if none. */
273  Block *m_current_block = nullptr;
274 
275  /** Start (inclusive) of the current free block. */
277 
278  /** End (exclusive) of the current free block. */
280 
281  /** Size of the _next_ block we intend to allocate. */
282  size_t m_block_size;
283 
284  /** The original block size the user asked for on construction. */
286 
287  /**
288  Maximum amount of memory this MEM_ROOT can hold. A value of 0
289  implies there is no limit.
290  */
291  size_t m_max_capacity = 0;
292 
293  /**
294  * Total allocated size for this MEM_ROOT. Does not include overhead
295  * for block headers or malloc overhead, since especially the latter
296  * is impossible to quantify portably.
297  */
298  size_t m_allocated_size = 0;
299 
300  /** If enabled, exceeding the capacity will lead to a my_error() call. */
302 
303  void (*m_error_handler)(void) = nullptr;
304 
306 };
307 
308 // Legacy C thunks. Do not use in new code.
310  size_t block_size, size_t) {
311  ::new (root) MEM_ROOT(key, block_size);
312 }
313 
314 static inline void *alloc_root(MEM_ROOT *root, size_t length) {
315  return root->Alloc(length);
316 }
317 
319 
320 static inline void claim_root(MEM_ROOT *root) { root->Claim(); }
321 
322 static inline void set_memroot_max_capacity(MEM_ROOT *root, size_t max_value) {
323  root->set_max_capacity(max_value);
324 }
325 
327  bool report_error) {
328  root->set_error_for_capacity_exceeded(report_error);
329 }
330 
331 static inline void reset_root_defaults(MEM_ROOT *root, size_t block_size,
332  size_t) {
333  root->set_block_size(block_size);
334 }
335 
336 /**
337  * Allocate an object of the given type. Use like this:
338  *
339  * Foo *foo = new (mem_root) Foo();
340  *
341  * Note that unlike regular operator new, this will not throw exceptions.
342  * However, it can return nullptr if the capacity of the MEM_ROOT has been
343  * reached. This is allowed since it is not a replacement for global operator
344  * new, and thus isn't used automatically by e.g. standard library containers.
345  *
346  * TODO: This syntax is confusing in that it could look like allocating
347  * a MEM_ROOT using regular placement new. We should make a less ambiguous
348  * syntax, e.g. new (On(mem_root)) Foo().
349  */
350 inline void *operator new(
351  size_t size, MEM_ROOT *mem_root,
352  const std::nothrow_t &arg MY_ATTRIBUTE((unused)) = std::nothrow) noexcept {
353  return mem_root->Alloc(size);
354 }
355 
356 inline void *operator new[](
357  size_t size, MEM_ROOT *mem_root,
358  const std::nothrow_t &arg MY_ATTRIBUTE((unused)) = std::nothrow) noexcept {
359  return mem_root->Alloc(size);
360 }
361 
362 inline void operator delete(void *, MEM_ROOT *,
363  const std::nothrow_t &)noexcept {
364  /* never called */
365 }
366 
367 inline void operator delete[](void *, MEM_ROOT *,
368  const std::nothrow_t &) noexcept {
369  /* never called */
370 }
371 
372 template <class T>
373 inline void destroy(T *ptr) {
374  if (ptr != nullptr) ptr->~T();
375 }
376 
377 template <class T>
378 inline void destroy_array(T *ptr, size_t count) {
379  static_assert(!std::is_pointer<T>::value,
380  "You're trying to destroy an array of pointers, "
381  "not an array of objects. This is probably not "
382  "what you intended.");
383  if (ptr != nullptr) {
384  for (size_t i = 0; i < count; ++i) destroy(&ptr[i]);
385  }
386 }
387 
388 /*
389  * For std::unique_ptr with objects allocated on a MEM_ROOT, you shouldn't use
390  * Default_deleter; use this deleter instead.
391  */
392 template <class T>
394  public:
395  void operator()(T *ptr) const { destroy(ptr); }
396 };
397 
398 /** std::unique_ptr, but only destroying. */
399 template <class T>
400 using unique_ptr_destroy_only = std::unique_ptr<T, Destroy_only<T>>;
401 
402 template <typename T, typename... Args>
404  Args &&... args) {
406  T(std::forward<Args>(args)...));
407 }
408 
409 #endif // INCLUDE_MY_ALLOC_H_
bool m_error_for_capacity_exceeded
If enabled, exceeding the capacity will lead to a my_error() call.
Definition: my_alloc.h:301
Block * prev
Definition: my_alloc.h:80
Block * AllocBlock(size_t length)
Allocate a new block of the given length (plus overhead for the block header).
Definition: my_alloc.cc:56
static void * alloc_root(MEM_ROOT *root, size_t length)
Definition: my_alloc.h:314
bool inited() const
Whether the constructor has run or not.
Definition: my_alloc.h:193
ssize_t count
Definition: memcached.c:386
static void set_memroot_error_reporting(MEM_ROOT *root, bool report_error)
Definition: my_alloc.h:326
Some integer typedefs for easier portability.
Definition: my_alloc.h:393
~MEM_ROOT()
Definition: my_alloc.h:119
void set_max_capacity(size_t max_capacity)
Set maximum capacity for this MEM_ROOT.
Definition: my_alloc.h:202
size_t m_max_capacity
Maximum amount of memory this MEM_ROOT can hold.
Definition: my_alloc.h:291
size_t get_max_capacity() const
Return maximum capacity for this MEM_ROOT.
Definition: my_alloc.h:207
#define malloc(A)
Definition: fts0ast.h:41
unique_ptr_destroy_only< T > make_unique_destroy_only(MEM_ROOT *mem_root, Args &&... args)
Definition: my_alloc.h:403
bool get_error_for_capacity_exceeded() const
Return whether error is to be reported when maximum capacity exceeds for MEM_ROOT.
Definition: my_alloc.h:225
static void set_memroot_max_capacity(MEM_ROOT *root, size_t max_value)
Definition: my_alloc.h:322
unsigned int PSI_memory_key
Instrumented memory key.
Definition: psi_memory_bits.h:46
unsigned int root
Definition: dbug_analyze.cc:514
static bool report_error(THD *thd, int error_code, Sql_condition::enum_severity_level level, Args... args)
Definition: error_handler.cc:281
void set_error_for_capacity_exceeded(bool report_error)
Enable/disable error reporting for exceeding the maximum capacity.
Definition: my_alloc.h:217
#define DBUG_EXECUTE_IF(keyword, a1)
Definition: my_dbug.h:100
void Clear()
Deallocate all the RAM used.
Definition: my_alloc.cc:138
size_t m_orig_block_size
The original block size the user asked for on construction.
Definition: my_alloc.h:285
size_t allocated_size() const
Amount of memory we have allocated from the operating system, not including overhead.
Definition: my_alloc.h:242
void Claim()
Claim all the allocated memory for the current thread in the performance schema.
Definition: my_alloc.cc:189
char * m_current_free_end
End (exclusive) of the current free block.
Definition: my_alloc.h:279
static void reset_root_defaults(MEM_ROOT *root, size_t block_size, size_t)
Definition: my_alloc.h:331
void set_error_handler(void(*error_handler)(void))
Set the error handler on memory allocation failure (or nullptr for none).
Definition: my_alloc.h:234
void ClearForReuse()
Similar to Clear(), but anticipates that the block will be reused for further allocations.
Definition: my_alloc.cc:157
Definition: my_alloc.h:79
Header for compiler-dependent features.
void * AllocSlow(size_t length)
Allocate memory that doesn&#39;t fit into the current free block.
Definition: my_alloc.cc:86
static void init_alloc_root(PSI_memory_key key, MEM_ROOT *root, size_t block_size, size_t)
Definition: my_alloc.h:309
static void FreeBlocks(Block *start)
Free all blocks in a linked list, starting at the given block.
Definition: my_alloc.cc:179
PSI_memory_key m_psi_key
Definition: my_alloc.h:305
size_t m_allocated_size
Total allocated size for this MEM_ROOT.
Definition: my_alloc.h:298
MEM_ROOT(PSI_memory_key key, size_t block_size)
Definition: my_alloc.h:86
static const char * key
Definition: suite_stubs.c:14
std::unique_ptr< T, Destroy_only< T > > unique_ptr_destroy_only
std::unique_ptr, but only destroying.
Definition: my_alloc.h:400
static MEM_ROOT mem_root
Definition: client_plugin.cc:107
Some macros for dealing with pointer arithmetic, e.g., aligning of buffers to a given size...
char * m_current_free_start
Start (inclusive) of the current free block.
Definition: my_alloc.h:276
Performance schema instrumentation interface.
int myf
Definition: my_inttypes.h:128
void destroy(T *ptr)
Definition: my_alloc.h:373
static void claim_root(MEM_ROOT *root)
Definition: my_alloc.h:320
static void start(PluginFuncEnv *env)
Definition: http_server_plugin.cc:484
void * Alloc(size_t length)
Allocate memory.
Definition: my_alloc.h:134
void(* m_error_handler)(void)
Definition: my_alloc.h:303
const string value("\alue\)
MEM_ROOT()
Definition: my_alloc.h:84
MEM_ROOT & operator=(MEM_ROOT &&other) noexcept
Definition: my_alloc.h:113
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:77
void operator()(T *ptr) const
Definition: my_alloc.h:395
Block * m_current_block
The current block we are giving out memory from.
Definition: my_alloc.h:273
static int flags[50]
Definition: hp_test1.cc:39
void set_block_size(size_t block_size)
Set the desired size of the next block to be allocated.
Definition: my_alloc.h:249
void free_root(MEM_ROOT *root, myf flags)
Definition: my_alloc.cc:255
MEM_ROOT & operator=(const MEM_ROOT &)=delete
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:75
size_t m_block_size
Size of the next block we intend to allocate.
Definition: my_alloc.h:282
noexcept m_psi_key(other.m_psi_key)
Definition: my_alloc.h:104
#define ALIGN_SIZE(A)
Definition: my_pointer_arithmetic.h:35
static char s_dummy_target
Something to point on that exists solely to never return nullptr from Alloc(0).
Definition: my_alloc.h:258
void destroy_array(T *ptr, size_t count)
Definition: my_alloc.h:378