Merge branch '976-disable-assert-checks' into 'master'
[glib.git] / glib / gmem.c
blobc4f42c545ffc1600e7a8b4c2d28fbb8239a25c25
1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
25 /*
26 * MT safe
29 #include "config.h"
31 #include "gmem.h"
33 #include <stdlib.h>
34 #include <string.h>
35 #include <signal.h>
37 #include "gslice.h"
38 #include "gbacktrace.h"
39 #include "gtestutils.h"
40 #include "gthread.h"
41 #include "glib_trace.h"
43 /* notes on macros:
44 * having G_DISABLE_CHECKS defined disables use of glib_mem_profiler_table and
45 * g_mem_profile().
46 * If g_mem_gc_friendly is TRUE, freed memory should be 0-wiped.
49 /* --- variables --- */
50 static GMemVTable glib_mem_vtable = {
51 malloc,
52 realloc,
53 free,
54 calloc,
55 malloc,
56 realloc,
59 /**
60 * SECTION:memory
61 * @Short_Description: general memory-handling
62 * @Title: Memory Allocation
64 * These functions provide support for allocating and freeing memory.
66 * If any call to allocate memory using functions g_new(), g_new0(), g_renew(),
67 * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n()
68 * fails, the application is terminated. This also means that there is no
69 * need to check if the call succeeded. On the other hand, g_try_...() family
70 * of functions returns %NULL on failure that can be used as a check
71 * for unsuccessful memory allocation. The application is not terminated
72 * in this case.
74 * It's important to match g_malloc() (and wrappers such as g_new()) with
75 * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
76 * g_slice_free(), plain malloc() with free(), and (if you're using C++)
77 * new with delete and new[] with delete[]. Otherwise bad things can happen,
78 * since these allocators may use different memory pools (and new/delete call
79 * constructors and destructors).
82 /* --- functions --- */
83 /**
84 * g_malloc:
85 * @n_bytes: the number of bytes to allocate
87 * Allocates @n_bytes bytes of memory.
88 * If @n_bytes is 0 it returns %NULL.
90 * Returns: a pointer to the allocated memory
92 gpointer
93 g_malloc (gsize n_bytes)
95 if (G_LIKELY (n_bytes))
97 gpointer mem;
99 mem = malloc (n_bytes);
100 TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 0));
101 if (mem)
102 return mem;
104 g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
105 G_STRLOC, n_bytes);
108 TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 0, 0));
110 return NULL;
114 * g_malloc0:
115 * @n_bytes: the number of bytes to allocate
117 * Allocates @n_bytes bytes of memory, initialized to 0's.
118 * If @n_bytes is 0 it returns %NULL.
120 * Returns: a pointer to the allocated memory
122 gpointer
123 g_malloc0 (gsize n_bytes)
125 if (G_LIKELY (n_bytes))
127 gpointer mem;
129 mem = calloc (1, n_bytes);
130 TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 1, 0));
131 if (mem)
132 return mem;
134 g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
135 G_STRLOC, n_bytes);
138 TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 1, 0));
140 return NULL;
144 * g_realloc:
145 * @mem: (nullable): the memory to reallocate
146 * @n_bytes: new size of the memory in bytes
148 * Reallocates the memory pointed to by @mem, so that it now has space for
149 * @n_bytes bytes of memory. It returns the new address of the memory, which may
150 * have been moved. @mem may be %NULL, in which case it's considered to
151 * have zero-length. @n_bytes may be 0, in which case %NULL will be returned
152 * and @mem will be freed unless it is %NULL.
154 * Returns: the new address of the allocated memory
156 gpointer
157 g_realloc (gpointer mem,
158 gsize n_bytes)
160 gpointer newmem;
162 if (G_LIKELY (n_bytes))
164 newmem = realloc (mem, n_bytes);
165 TRACE (GLIB_MEM_REALLOC((void*) newmem, (void*)mem, (unsigned int) n_bytes, 0));
166 if (newmem)
167 return newmem;
169 g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
170 G_STRLOC, n_bytes);
173 if (mem)
174 free (mem);
176 TRACE (GLIB_MEM_REALLOC((void*) NULL, (void*)mem, 0, 0));
178 return NULL;
182 * g_free:
183 * @mem: (nullable): the memory to free
185 * Frees the memory pointed to by @mem.
187 * If @mem is %NULL it simply returns, so there is no need to check @mem
188 * against %NULL before calling this function.
190 void
191 g_free (gpointer mem)
193 if (G_LIKELY (mem))
194 free (mem);
195 TRACE(GLIB_MEM_FREE((void*) mem));
199 * g_clear_pointer: (skip)
200 * @pp: (not nullable): a pointer to a variable, struct member etc. holding a
201 * pointer
202 * @destroy: a function to which a gpointer can be passed, to destroy *@pp
204 * Clears a reference to a variable.
206 * @pp must not be %NULL.
208 * If the reference is %NULL then this function does nothing.
209 * Otherwise, the variable is destroyed using @destroy and the
210 * pointer is set to %NULL.
212 * A macro is also included that allows this function to be used without
213 * pointer casts.
215 * Since: 2.34
217 #undef g_clear_pointer
218 void
219 g_clear_pointer (gpointer *pp,
220 GDestroyNotify destroy)
222 gpointer _p;
224 _p = *pp;
225 if (_p)
227 *pp = NULL;
228 destroy (_p);
233 * g_try_malloc:
234 * @n_bytes: number of bytes to allocate.
236 * Attempts to allocate @n_bytes, and returns %NULL on failure.
237 * Contrast with g_malloc(), which aborts the program on failure.
239 * Returns: the allocated memory, or %NULL.
241 gpointer
242 g_try_malloc (gsize n_bytes)
244 gpointer mem;
246 if (G_LIKELY (n_bytes))
247 mem = malloc (n_bytes);
248 else
249 mem = NULL;
251 TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 1));
253 return mem;
257 * g_try_malloc0:
258 * @n_bytes: number of bytes to allocate
260 * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
261 * failure. Contrast with g_malloc0(), which aborts the program on failure.
263 * Since: 2.8
264 * Returns: the allocated memory, or %NULL
266 gpointer
267 g_try_malloc0 (gsize n_bytes)
269 gpointer mem;
271 if (G_LIKELY (n_bytes))
272 mem = calloc (1, n_bytes);
273 else
274 mem = NULL;
276 return mem;
280 * g_try_realloc:
281 * @mem: (nullable): previously-allocated memory, or %NULL.
282 * @n_bytes: number of bytes to allocate.
284 * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
285 * on failure. Contrast with g_realloc(), which aborts the program
286 * on failure.
288 * If @mem is %NULL, behaves the same as g_try_malloc().
290 * Returns: the allocated memory, or %NULL.
292 gpointer
293 g_try_realloc (gpointer mem,
294 gsize n_bytes)
296 gpointer newmem;
298 if (G_LIKELY (n_bytes))
299 newmem = realloc (mem, n_bytes);
300 else
302 newmem = NULL;
303 if (mem)
304 free (mem);
307 TRACE (GLIB_MEM_REALLOC((void*) newmem, (void*)mem, (unsigned int) n_bytes, 1));
309 return newmem;
313 #define SIZE_OVERFLOWS(a,b) (G_UNLIKELY ((b) > 0 && (a) > G_MAXSIZE / (b)))
316 * g_malloc_n:
317 * @n_blocks: the number of blocks to allocate
318 * @n_block_bytes: the size of each block in bytes
320 * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
321 * but care is taken to detect possible overflow during multiplication.
323 * Since: 2.24
324 * Returns: a pointer to the allocated memory
326 gpointer
327 g_malloc_n (gsize n_blocks,
328 gsize n_block_bytes)
330 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
332 g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
333 G_STRLOC, n_blocks, n_block_bytes);
336 return g_malloc (n_blocks * n_block_bytes);
340 * g_malloc0_n:
341 * @n_blocks: the number of blocks to allocate
342 * @n_block_bytes: the size of each block in bytes
344 * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
345 * but care is taken to detect possible overflow during multiplication.
347 * Since: 2.24
348 * Returns: a pointer to the allocated memory
350 gpointer
351 g_malloc0_n (gsize n_blocks,
352 gsize n_block_bytes)
354 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
356 g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
357 G_STRLOC, n_blocks, n_block_bytes);
360 return g_malloc0 (n_blocks * n_block_bytes);
364 * g_realloc_n:
365 * @mem: (nullable): the memory to reallocate
366 * @n_blocks: the number of blocks to allocate
367 * @n_block_bytes: the size of each block in bytes
369 * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
370 * but care is taken to detect possible overflow during multiplication.
372 * Since: 2.24
373 * Returns: the new address of the allocated memory
375 gpointer
376 g_realloc_n (gpointer mem,
377 gsize n_blocks,
378 gsize n_block_bytes)
380 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
382 g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
383 G_STRLOC, n_blocks, n_block_bytes);
386 return g_realloc (mem, n_blocks * n_block_bytes);
390 * g_try_malloc_n:
391 * @n_blocks: the number of blocks to allocate
392 * @n_block_bytes: the size of each block in bytes
394 * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
395 * but care is taken to detect possible overflow during multiplication.
397 * Since: 2.24
398 * Returns: the allocated memory, or %NULL.
400 gpointer
401 g_try_malloc_n (gsize n_blocks,
402 gsize n_block_bytes)
404 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
405 return NULL;
407 return g_try_malloc (n_blocks * n_block_bytes);
411 * g_try_malloc0_n:
412 * @n_blocks: the number of blocks to allocate
413 * @n_block_bytes: the size of each block in bytes
415 * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
416 * but care is taken to detect possible overflow during multiplication.
418 * Since: 2.24
419 * Returns: the allocated memory, or %NULL
421 gpointer
422 g_try_malloc0_n (gsize n_blocks,
423 gsize n_block_bytes)
425 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
426 return NULL;
428 return g_try_malloc0 (n_blocks * n_block_bytes);
432 * g_try_realloc_n:
433 * @mem: (nullable): previously-allocated memory, or %NULL.
434 * @n_blocks: the number of blocks to allocate
435 * @n_block_bytes: the size of each block in bytes
437 * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
438 * but care is taken to detect possible overflow during multiplication.
440 * Since: 2.24
441 * Returns: the allocated memory, or %NULL.
443 gpointer
444 g_try_realloc_n (gpointer mem,
445 gsize n_blocks,
446 gsize n_block_bytes)
448 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
449 return NULL;
451 return g_try_realloc (mem, n_blocks * n_block_bytes);
455 * g_mem_is_system_malloc:
457 * Checks whether the allocator used by g_malloc() is the system's
458 * malloc implementation. If it returns %TRUE memory allocated with
459 * malloc() can be used interchangeable with memory allocated using g_malloc().
460 * This function is useful for avoiding an extra copy of allocated memory returned
461 * by a non-GLib-based API.
463 * Returns: if %TRUE, malloc() and g_malloc() can be mixed.
465 * Deprecated: 2.46: GLib always uses the system malloc, so this function always
466 * returns %TRUE.
468 gboolean
469 g_mem_is_system_malloc (void)
471 return TRUE;
475 * g_mem_set_vtable:
476 * @vtable: table of memory allocation routines.
478 * This function used to let you override the memory allocation function.
479 * However, its use was incompatible with the use of global constructors
480 * in GLib and GIO, because those use the GLib allocators before main is
481 * reached. Therefore this function is now deprecated and is just a stub.
483 * Deprecated: 2.46: This function now does nothing. Use other memory
484 * profiling tools instead
486 void
487 g_mem_set_vtable (GMemVTable *vtable)
489 g_warning (G_STRLOC ": custom memory allocation vtable not supported");
494 * glib_mem_profiler_table:
496 * Used to be a #GMemVTable containing profiling variants of the memory
497 * allocation functions, but this variable shouldn't be modified anymore.
499 * Deprecated: 2.46: Use other memory profiling tools instead
501 GMemVTable *glib_mem_profiler_table = &glib_mem_vtable;
504 * g_mem_profile:
506 * GLib used to support some tools for memory profiling, but this
507 * no longer works. There are many other useful tools for memory
508 * profiling these days which can be used instead.
510 * Deprecated: 2.46: Use other memory profiling tools instead
512 void
513 g_mem_profile (void)
515 g_warning (G_STRLOC ": memory profiling not supported");