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 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/.
38 #include "gbacktrace.h"
39 #include "gtestutils.h"
41 #include "glib_trace.h"
44 * having G_DISABLE_CHECKS defined disables use of glib_mem_profiler_table and
46 * If g_mem_gc_friendly is TRUE, freed memory should be 0-wiped.
49 /* --- variables --- */
50 static GMemVTable glib_mem_vtable = {
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 fails, the application is terminated.
67 * This also means that there is no need to check if the call succeeded.
69 * It's important to match g_malloc() (and wrappers such as g_new()) with
70 * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
71 * g_slice_free(), plain malloc() with free(), and (if you're using C++)
72 * new with delete and new[] with delete[]. Otherwise bad things can happen,
73 * since these allocators may use different memory pools (and new/delete call
74 * constructors and destructors).
77 /* --- functions --- */
80 * @n_bytes: the number of bytes to allocate
82 * Allocates @n_bytes bytes of memory.
83 * If @n_bytes is 0 it returns %NULL.
85 * Returns: a pointer to the allocated memory
88 g_malloc (gsize n_bytes)
90 if (G_LIKELY (n_bytes))
94 mem = malloc (n_bytes);
95 TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 0));
99 g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
103 TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 0, 0));
110 * @n_bytes: the number of bytes to allocate
112 * Allocates @n_bytes bytes of memory, initialized to 0's.
113 * If @n_bytes is 0 it returns %NULL.
115 * Returns: a pointer to the allocated memory
118 g_malloc0 (gsize n_bytes)
120 if (G_LIKELY (n_bytes))
124 mem = calloc (1, n_bytes);
125 TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 1, 0));
129 g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
133 TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 1, 0));
140 * @mem: (allow-none): the memory to reallocate
141 * @n_bytes: new size of the memory in bytes
143 * Reallocates the memory pointed to by @mem, so that it now has space for
144 * @n_bytes bytes of memory. It returns the new address of the memory, which may
145 * have been moved. @mem may be %NULL, in which case it's considered to
146 * have zero-length. @n_bytes may be 0, in which case %NULL will be returned
147 * and @mem will be freed unless it is %NULL.
149 * Returns: the new address of the allocated memory
152 g_realloc (gpointer mem,
157 if (G_LIKELY (n_bytes))
159 newmem = realloc (mem, n_bytes);
160 TRACE (GLIB_MEM_REALLOC((void*) newmem, (void*)mem, (unsigned int) n_bytes, 0));
164 g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
171 TRACE (GLIB_MEM_REALLOC((void*) NULL, (void*)mem, 0, 0));
178 * @mem: (allow-none): the memory to free
180 * Frees the memory pointed to by @mem.
182 * If @mem is %NULL it simply returns, so there is no need to check @mem
183 * against %NULL before calling this function.
186 g_free (gpointer mem)
190 TRACE(GLIB_MEM_FREE((void*) mem));
194 * g_clear_pointer: (skip)
195 * @pp: a pointer to a variable, struct member etc. holding a pointer
196 * @destroy: a function to which a gpointer can be passed, to destroy *@pp
198 * Clears a reference to a variable.
200 * @pp must not be %NULL.
202 * If the reference is %NULL then this function does nothing.
203 * Otherwise, the variable is destroyed using @destroy and the
204 * pointer is set to %NULL.
206 * A macro is also included that allows this function to be used without
211 #undef g_clear_pointer
213 g_clear_pointer (gpointer *pp,
214 GDestroyNotify destroy)
228 * @n_bytes: number of bytes to allocate.
230 * Attempts to allocate @n_bytes, and returns %NULL on failure.
231 * Contrast with g_malloc(), which aborts the program on failure.
233 * Returns: the allocated memory, or %NULL.
236 g_try_malloc (gsize n_bytes)
240 if (G_LIKELY (n_bytes))
241 mem = malloc (n_bytes);
245 TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 1));
252 * @n_bytes: number of bytes to allocate
254 * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
255 * failure. Contrast with g_malloc0(), which aborts the program on failure.
258 * Returns: the allocated memory, or %NULL
261 g_try_malloc0 (gsize n_bytes)
265 if (G_LIKELY (n_bytes))
266 mem = calloc (1, n_bytes);
275 * @mem: (allow-none): previously-allocated memory, or %NULL.
276 * @n_bytes: number of bytes to allocate.
278 * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
279 * on failure. Contrast with g_realloc(), which aborts the program
282 * If @mem is %NULL, behaves the same as g_try_malloc().
284 * Returns: the allocated memory, or %NULL.
287 g_try_realloc (gpointer mem,
292 if (G_LIKELY (n_bytes))
293 newmem = realloc (mem, n_bytes);
301 TRACE (GLIB_MEM_REALLOC((void*) newmem, (void*)mem, (unsigned int) n_bytes, 1));
307 #define SIZE_OVERFLOWS(a,b) (G_UNLIKELY ((b) > 0 && (a) > G_MAXSIZE / (b)))
311 * @n_blocks: the number of blocks to allocate
312 * @n_block_bytes: the size of each block in bytes
314 * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
315 * but care is taken to detect possible overflow during multiplication.
318 * Returns: a pointer to the allocated memory
321 g_malloc_n (gsize n_blocks,
324 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
326 g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
327 G_STRLOC, n_blocks, n_block_bytes);
330 return g_malloc (n_blocks * n_block_bytes);
335 * @n_blocks: the number of blocks to allocate
336 * @n_block_bytes: the size of each block in bytes
338 * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
339 * but care is taken to detect possible overflow during multiplication.
342 * Returns: a pointer to the allocated memory
345 g_malloc0_n (gsize n_blocks,
348 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
350 g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
351 G_STRLOC, n_blocks, n_block_bytes);
354 return g_malloc0 (n_blocks * n_block_bytes);
359 * @mem: (allow-none): the memory to reallocate
360 * @n_blocks: the number of blocks to allocate
361 * @n_block_bytes: the size of each block in bytes
363 * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
364 * but care is taken to detect possible overflow during multiplication.
367 * Returns: the new address of the allocated memory
370 g_realloc_n (gpointer mem,
374 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
376 g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
377 G_STRLOC, n_blocks, n_block_bytes);
380 return g_realloc (mem, n_blocks * n_block_bytes);
385 * @n_blocks: the number of blocks to allocate
386 * @n_block_bytes: the size of each block in bytes
388 * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
389 * but care is taken to detect possible overflow during multiplication.
392 * Returns: the allocated memory, or %NULL.
395 g_try_malloc_n (gsize n_blocks,
398 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
401 return g_try_malloc (n_blocks * n_block_bytes);
406 * @n_blocks: the number of blocks to allocate
407 * @n_block_bytes: the size of each block in bytes
409 * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
410 * but care is taken to detect possible overflow during multiplication.
413 * Returns: the allocated memory, or %NULL
416 g_try_malloc0_n (gsize n_blocks,
419 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
422 return g_try_malloc0 (n_blocks * n_block_bytes);
427 * @mem: (allow-none): previously-allocated memory, or %NULL.
428 * @n_blocks: the number of blocks to allocate
429 * @n_block_bytes: the size of each block in bytes
431 * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
432 * but care is taken to detect possible overflow during multiplication.
435 * Returns: the allocated memory, or %NULL.
438 g_try_realloc_n (gpointer mem,
442 if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
445 return g_try_realloc (mem, n_blocks * n_block_bytes);
449 * g_mem_is_system_malloc:
451 * Checks whether the allocator used by g_malloc() is the system's
452 * malloc implementation. If it returns %TRUE memory allocated with
453 * malloc() can be used interchangeable with memory allocated using g_malloc().
454 * This function is useful for avoiding an extra copy of allocated memory returned
455 * by a non-GLib-based API.
457 * Returns: if %TRUE, malloc() and g_malloc() can be mixed.
459 * Deprecated: 2.46: GLib always uses the system malloc, so this function always
463 g_mem_is_system_malloc (void)
470 * @vtable: table of memory allocation routines.
472 * This function used to let you override the memory allocation function.
473 * However, its use was incompatible with the use of global constructors
474 * in GLib and GIO, because those use the GLib allocators before main is
475 * reached. Therefore this function is now deprecated and is just a stub.
477 * Deprecated: 2.46: Use other memory profiling tools instead
480 g_mem_set_vtable (GMemVTable *vtable)
482 g_warning (G_STRLOC ": custom memory allocation vtable not supported");
487 * glib_mem_profiler_table:
489 * Deprecated: 2.46: Use other memory profiling tools instead
491 GMemVTable *glib_mem_profiler_table = &glib_mem_vtable;
496 * GLib used to support some tools for memory profiling, but this
497 * no longer works. There are many other useful tools for memory
498 * profiling these days which can be used instead.
500 * Deprecated: 2.46: Use other memory profiling tools instead
505 g_warning (G_STRLOC ": memory profiling not supported");