MySQL  8.0.17
Source Code Documentation
my_alloc.h
Go to the documentation of this file.
1 /* Copyright (c) 2000, 2019, 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  Allocate “num” objects of type T, and default-construct them.
159  If the constructor throws an exception, behavior is undefined.
160 
161  We don't use new[], as it can put extra data in front of the array.
162  */
163  template <class T>
164  T *ArrayAlloc(size_t num) {
165  static_assert(alignof(T) <= 8, "MEM_ROOT only returns 8-aligned memory.");
166  if (num * sizeof(T) < num) {
167  // Overflow.
168  return nullptr;
169  }
170  T *ret = static_cast<T *>(Alloc(num * sizeof(T)));
171 
172  // Default-construct all elements. For primitive types like int,
173  // the entire loop will be optimized away.
174  for (size_t i = 0; i < num; ++i) {
175  new (&ret[i]) T;
176  }
177 
178  return ret;
179  }
180 
181  /**
182  * Claim all the allocated memory for the current thread in the performance
183  * schema. Use when transferring responsibility for a MEM_ROOT from one thread
184  * to another.
185  */
186  void Claim();
187 
188  /**
189  * Deallocate all the RAM used. The MEM_ROOT itself continues to be valid,
190  * so you can make new calls to Alloc() afterwards.
191 
192  * @note
193  * One can call this function either with a MEM_ROOT initialized with the
194  * constructor, or with one that's memset() to all zeros.
195  * It's also safe to call this multiple times with the same mem_root.
196  */
197  void Clear();
198 
199  /**
200  * Similar to Clear(), but anticipates that the block will be reused for
201  * further allocations. This means that even though all the data is gone,
202  * one memory block (typically the largest allocated) will be kept and
203  * made immediately available for calls to Alloc() without having to go to the
204  * OS for new memory. This can yield performance gains if you use the same
205  * MEM_ROOT many times. Also, the block size is not reset.
206  */
207  void ClearForReuse();
208 
209  /**
210  Whether the constructor has run or not.
211 
212  This exists solely to support legacy code that memset()s the MEM_ROOT to
213  all zeros, which wants to distinguish between that state and a properly
214  initialized MEM_ROOT. If you do not run the constructor _nor_ do memset(),
215  you are invoking undefined behavior.
216  */
217  bool inited() const { return m_block_size != 0; }
218 
219  /**
220  * Set maximum capacity for this MEM_ROOT. Whenever the MEM_ROOT has
221  * allocated more than this (not including overhead), and the free block
222  * is empty, future allocations will fail.
223  *
224  * @param max_capacity Maximum capacity this mem_root can hold
225  */
226  void set_max_capacity(size_t max_capacity) { m_max_capacity = max_capacity; }
227 
228  /**
229  * Return maximum capacity for this MEM_ROOT.
230  */
231  size_t get_max_capacity() const { return m_max_capacity; }
232 
233  /**
234  * Enable/disable error reporting for exceeding the maximum capacity.
235  * If error reporting is enabled, an error is flagged to indicate that the
236  * capacity is exceeded. However, allocation will still happen for the
237  * requested memory.
238  *
239  * @param report_error whether the error should be reported
240  */
243  }
244 
245  /**
246  * Return whether error is to be reported when
247  * maximum capacity exceeds for MEM_ROOT.
248  */
251  }
252 
253  /**
254  * Set the error handler on memory allocation failure (or nullptr for none).
255  * The error handler is called called whenever my_malloc() failed to allocate
256  * more memory from the OS (which causes my_alloc() to return nullptr).
257  */
258  void set_error_handler(void (*error_handler)(void)) {
259  m_error_handler = error_handler;
260  }
261 
262  /**
263  * Amount of memory we have allocated from the operating system, not including
264  * overhead.
265  */
266  size_t allocated_size() const { return m_allocated_size; }
267 
268  /**
269  * Set the desired size of the next block to be allocated. Note that future
270  * allocations
271  * will grow in size over this, although a Clear() will reset the size again.
272  */
273  void set_block_size(size_t block_size) {
274  m_block_size = m_orig_block_size = block_size;
275  }
276 
277  private:
278  /**
279  * Something to point on that exists solely to never return nullptr
280  * from Alloc(0).
281  */
282  static char s_dummy_target;
283 
284  /**
285  Allocate a new block of the given length (plus overhead for the block
286  header).
287  */
288  Block *AllocBlock(size_t length);
289 
290  /** Allocate memory that doesn't fit into the current free block. */
291  void *AllocSlow(size_t length);
292 
293  /** Free all blocks in a linked list, starting at the given block. */
294  static void FreeBlocks(Block *start);
295 
296  /** The current block we are giving out memory from. nullptr if none. */
297  Block *m_current_block = nullptr;
298 
299  /** Start (inclusive) of the current free block. */
301 
302  /** End (exclusive) of the current free block. */
304 
305  /** Size of the _next_ block we intend to allocate. */
306  size_t m_block_size;
307 
308  /** The original block size the user asked for on construction. */
310 
311  /**
312  Maximum amount of memory this MEM_ROOT can hold. A value of 0
313  implies there is no limit.
314  */
315  size_t m_max_capacity = 0;
316 
317  /**
318  * Total allocated size for this MEM_ROOT. Does not include overhead
319  * for block headers or malloc overhead, since especially the latter
320  * is impossible to quantify portably.
321  */
322  size_t m_allocated_size = 0;
323 
324  /** If enabled, exceeding the capacity will lead to a my_error() call. */
326 
327  void (*m_error_handler)(void) = nullptr;
328 
330 };
331 
332 // Legacy C thunks. Do not use in new code.
334  size_t block_size, size_t) {
335  ::new (root) MEM_ROOT(key, block_size);
336 }
337 
339 
340 /**
341  * Allocate an object of the given type. Use like this:
342  *
343  * Foo *foo = new (mem_root) Foo();
344  *
345  * Note that unlike regular operator new, this will not throw exceptions.
346  * However, it can return nullptr if the capacity of the MEM_ROOT has been
347  * reached. This is allowed since it is not a replacement for global operator
348  * new, and thus isn't used automatically by e.g. standard library containers.
349  *
350  * TODO: This syntax is confusing in that it could look like allocating
351  * a MEM_ROOT using regular placement new. We should make a less ambiguous
352  * syntax, e.g. new (On(mem_root)) Foo().
353  */
354 inline void *operator new(
355  size_t size, MEM_ROOT *mem_root,
356  const std::nothrow_t &arg MY_ATTRIBUTE((unused)) = std::nothrow) noexcept {
357  return mem_root->Alloc(size);
358 }
359 
360 inline void *operator new[](
361  size_t size, MEM_ROOT *mem_root,
362  const std::nothrow_t &arg MY_ATTRIBUTE((unused)) = std::nothrow) noexcept {
363  return mem_root->Alloc(size);
364 }
365 
366 inline void operator delete(void *, MEM_ROOT *,
367  const std::nothrow_t &)noexcept {
368  /* never called */
369 }
370 
371 inline void operator delete[](void *, MEM_ROOT *,
372  const std::nothrow_t &) noexcept {
373  /* never called */
374 }
375 
376 template <class T>
377 inline void destroy(T *ptr) {
378  if (ptr != nullptr) ptr->~T();
379 }
380 
381 template <class T>
382 inline void destroy_array(T *ptr, size_t count) {
383  static_assert(!std::is_pointer<T>::value,
384  "You're trying to destroy an array of pointers, "
385  "not an array of objects. This is probably not "
386  "what you intended.");
387  if (ptr != nullptr) {
388  for (size_t i = 0; i < count; ++i) destroy(&ptr[i]);
389  }
390 }
391 
392 /*
393  * For std::unique_ptr with objects allocated on a MEM_ROOT, you shouldn't use
394  * Default_deleter; use this deleter instead.
395  */
396 template <class T>
398  public:
399  void operator()(T *ptr) const { destroy(ptr); }
400 };
401 
402 /** std::unique_ptr, but only destroying. */
403 template <class T>
404 using unique_ptr_destroy_only = std::unique_ptr<T, Destroy_only<T>>;
405 
406 template <typename T, typename... Args>
408  Args &&... args) {
410  T(std::forward<Args>(args)...));
411 }
412 
413 #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:325
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
bool inited() const
Whether the constructor has run or not.
Definition: my_alloc.h:217
ssize_t count
Definition: memcached.c:386
Some integer typedefs for easier portability.
Definition: my_alloc.h:397
~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:226
size_t m_max_capacity
Maximum amount of memory this MEM_ROOT can hold.
Definition: my_alloc.h:315
size_t get_max_capacity() const
Return maximum capacity for this MEM_ROOT.
Definition: my_alloc.h:231
#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:407
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:249
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:241
#define DBUG_EXECUTE_IF(keyword, a1)
Definition: my_dbug.h:155
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:309
size_t allocated_size() const
Amount of memory we have allocated from the operating system, not including overhead.
Definition: my_alloc.h:266
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:303
void set_error_handler(void(*error_handler)(void))
Set the error handler on memory allocation failure (or nullptr for none).
Definition: my_alloc.h:258
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:333
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:329
size_t m_allocated_size
Total allocated size for this MEM_ROOT.
Definition: my_alloc.h:322
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:404
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...
T * ArrayAlloc(size_t num)
Allocate “num” objects of type T, and default-construct them.
Definition: my_alloc.h:164
char * m_current_free_start
Start (inclusive) of the current free block.
Definition: my_alloc.h:300
Performance schema instrumentation interface.
int myf
Definition: my_inttypes.h:121
void destroy(T *ptr)
Definition: my_alloc.h:377
static void start(PluginFuncEnv *env)
Definition: http_server_plugin.cc:572
void * Alloc(size_t length)
Allocate memory.
Definition: my_alloc.h:134
void(* m_error_handler)(void)
Definition: my_alloc.h:327
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:399
Block * m_current_block
The current block we are giving out memory from.
Definition: my_alloc.h:297
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:273
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:306
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:282
void destroy_array(T *ptr, size_t count)
Definition: my_alloc.h:382