glib/gmem.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   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.
   8  *
   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.
  13  *
  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/>.
  16  */
  17
  18 /*
  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/.
  23  */
  24
  25 /*
  26  * MT safe
  27  */
  28
  29 #include "config.h"
  30
  31 #include "gmem.h"
  32
  33 #include <stdlib.h>
  34 #include <string.h>
  35 #include <signal.h>
  36
  37 #include "gslice.h"
  38 #include "gbacktrace.h"
  39 #include "gtestutils.h"
  40 #include "gthread.h"
  41 #include "glib_trace.h"
  42
  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.
  47  */
  48
  49 /* --- variables --- */
  50 static GMemVTable glib_mem_vtable = {
  51   malloc,
  52   realloc,
  53   free,
  54   calloc,
  55   malloc,
  56   realloc,
  57 };
  58
  59 /**
  60  * SECTION:memory
  61  * @Short_Description: general memory-handling
  62  * @Title: Memory Allocation
  63  *
  64  * These functions provide support for allocating and freeing memory.
  65  *
  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.
  73  *
  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).
  80  */
  81
  82 /* --- functions --- */
  83 /**
  84  * g_malloc:
  85  * @n_bytes: the number of bytes to allocate
  86  *
  87  * Allocates @n_bytes bytes of memory.
  88  * If @n_bytes is 0 it returns %NULL.
  89  *
  90  * Returns: a pointer to the allocated memory
  91  */
  92 gpointer
  93 g_malloc (gsize n_bytes)
  94 {
  95   if (G_LIKELY (n_bytes))
  96     {
  97       gpointer mem;
  98
  99       mem = malloc (n_bytes);
 100       TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 0));
 101       if (mem)
 102         return mem;
 103
 104       g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
 105                G_STRLOC, n_bytes);
 106     }
 107
 108   TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 0, 0));
 109
 110   return NULL;
 111 }
 112
 113 /**
 114  * g_malloc0:
 115  * @n_bytes: the number of bytes to allocate
 116  *
 117  * Allocates @n_bytes bytes of memory, initialized to 0's.
 118  * If @n_bytes is 0 it returns %NULL.
 119  *
 120  * Returns: a pointer to the allocated memory
 121  */
 122 gpointer
 123 g_malloc0 (gsize n_bytes)
 124 {
 125   if (G_LIKELY (n_bytes))
 126     {
 127       gpointer mem;
 128
 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;
 133
 134       g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
 135                G_STRLOC, n_bytes);
 136     }
 137
 138   TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 1, 0));
 139
 140   return NULL;
 141 }
 142
 143 /**
 144  * g_realloc:
 145  * @mem: (nullable): the memory to reallocate
 146  * @n_bytes: new size of the memory in bytes
 147  *
 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.
 153  *
 154  * Returns: the new address of the allocated memory
 155  */
 156 gpointer
 157 g_realloc (gpointer mem,
 158            gsize    n_bytes)
 159 {
 160   gpointer newmem;
 161
 162   if (G_LIKELY (n_bytes))
 163     {
 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;
 168
 169       g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
 170                G_STRLOC, n_bytes);
 171     }
 172
 173   if (mem)
 174     free (mem);
 175
 176   TRACE (GLIB_MEM_REALLOC((void*) NULL, (void*)mem, 0, 0));
 177
 178   return NULL;
 179 }
 180
 181 /**
 182  * g_free:
 183  * @mem: (nullable): the memory to free
 184  *
 185  * Frees the memory pointed to by @mem.
 186  *
 187  * If @mem is %NULL it simply returns, so there is no need to check @mem
 188  * against %NULL before calling this function.
 189  */
 190 void
 191 g_free (gpointer mem)
 192 {
 193   if (G_LIKELY (mem))
 194     free (mem);
 195   TRACE(GLIB_MEM_FREE((void*) mem));
 196 }
 197
 198 /**
 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
 203  *
 204  * Clears a reference to a variable.
 205  *
 206  * @pp must not be %NULL.
 207  *
 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.
 211  *
 212  * A macro is also included that allows this function to be used without
 213  * pointer casts.
 214  *
 215  * Since: 2.34
 216  **/
 217 #undef g_clear_pointer
 218 void
 219 g_clear_pointer (gpointer      *pp,
 220                  GDestroyNotify destroy)
 221 {
 222   gpointer _p;
 223
 224   _p = *pp;
 225   if (_p)
 226     {
 227       *pp = NULL;
 228       destroy (_p);
 229     }
 230 }
 231
 232 /**
 233  * g_try_malloc:
 234  * @n_bytes: number of bytes to allocate.
 235  *
 236  * Attempts to allocate @n_bytes, and returns %NULL on failure.
 237  * Contrast with g_malloc(), which aborts the program on failure.
 238  *
 239  * Returns: the allocated memory, or %NULL.
 240  */
 241 gpointer
 242 g_try_malloc (gsize n_bytes)
 243 {
 244   gpointer mem;
 245
 246   if (G_LIKELY (n_bytes))
 247     mem = malloc (n_bytes);
 248   else
 249     mem = NULL;
 250
 251   TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 1));
 252
 253   return mem;
 254 }
 255
 256 /**
 257  * g_try_malloc0:
 258  * @n_bytes: number of bytes to allocate
 259  *
 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.
 262  *
 263  * Since: 2.8
 264  * Returns: the allocated memory, or %NULL
 265  */
 266 gpointer
 267 g_try_malloc0 (gsize n_bytes)
 268 {
 269   gpointer mem;
 270
 271   if (G_LIKELY (n_bytes))
 272     mem = calloc (1, n_bytes);
 273   else
 274     mem = NULL;
 275
 276   return mem;
 277 }
 278
 279 /**
 280  * g_try_realloc:
 281  * @mem: (nullable): previously-allocated memory, or %NULL.
 282  * @n_bytes: number of bytes to allocate.
 283  *
 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.
 287  *
 288  * If @mem is %NULL, behaves the same as g_try_malloc().
 289  *
 290  * Returns: the allocated memory, or %NULL.
 291  */
 292 gpointer
 293 g_try_realloc (gpointer mem,
 294                gsize    n_bytes)
 295 {
 296   gpointer newmem;
 297
 298   if (G_LIKELY (n_bytes))
 299     newmem = realloc (mem, n_bytes);
 300   else
 301     {
 302       newmem = NULL;
 303       if (mem)
 304         free (mem);
 305     }
 306
 307   TRACE (GLIB_MEM_REALLOC((void*) newmem, (void*)mem, (unsigned int) n_bytes, 1));
 308
 309   return newmem;
 310 }
 311
 312
 313 #define SIZE_OVERFLOWS(a,b) (G_UNLIKELY ((b) > 0 && (a) > G_MAXSIZE / (b)))
 314
 315 /**
 316  * g_malloc_n:
 317  * @n_blocks: the number of blocks to allocate
 318  * @n_block_bytes: the size of each block in bytes
 319  *
 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.
 322  *
 323  * Since: 2.24
 324  * Returns: a pointer to the allocated memory
 325  */
 326 gpointer
 327 g_malloc_n (gsize n_blocks,
 328             gsize n_block_bytes)
 329 {
 330   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 331     {
 332       g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
 333                G_STRLOC, n_blocks, n_block_bytes);
 334     }
 335
 336   return g_malloc (n_blocks * n_block_bytes);
 337 }
 338
 339 /**
 340  * g_malloc0_n:
 341  * @n_blocks: the number of blocks to allocate
 342  * @n_block_bytes: the size of each block in bytes
 343  *
 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.
 346  *
 347  * Since: 2.24
 348  * Returns: a pointer to the allocated memory
 349  */
 350 gpointer
 351 g_malloc0_n (gsize n_blocks,
 352              gsize n_block_bytes)
 353 {
 354   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 355     {
 356       g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
 357                G_STRLOC, n_blocks, n_block_bytes);
 358     }
 359
 360   return g_malloc0 (n_blocks * n_block_bytes);
 361 }
 362
 363 /**
 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
 368  *
 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.
 371  *
 372  * Since: 2.24
 373  * Returns: the new address of the allocated memory
 374  */
 375 gpointer
 376 g_realloc_n (gpointer mem,
 377              gsize    n_blocks,
 378              gsize    n_block_bytes)
 379 {
 380   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 381     {
 382       g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
 383                G_STRLOC, n_blocks, n_block_bytes);
 384     }
 385
 386   return g_realloc (mem, n_blocks * n_block_bytes);
 387 }
 388
 389 /**
 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
 393  *
 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.
 396  *
 397  * Since: 2.24
 398  * Returns: the allocated memory, or %NULL.
 399  */
 400 gpointer
 401 g_try_malloc_n (gsize n_blocks,
 402                 gsize n_block_bytes)
 403 {
 404   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 405     return NULL;
 406
 407   return g_try_malloc (n_blocks * n_block_bytes);
 408 }
 409
 410 /**
 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
 414  *
 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.
 417  *
 418  * Since: 2.24
 419  * Returns: the allocated memory, or %NULL
 420  */
 421 gpointer
 422 g_try_malloc0_n (gsize n_blocks,
 423                  gsize n_block_bytes)
 424 {
 425   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 426     return NULL;
 427
 428   return g_try_malloc0 (n_blocks * n_block_bytes);
 429 }
 430
 431 /**
 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
 436  *
 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.
 439  *
 440  * Since: 2.24
 441  * Returns: the allocated memory, or %NULL.
 442  */
 443 gpointer
 444 g_try_realloc_n (gpointer mem,
 445                  gsize    n_blocks,
 446                  gsize    n_block_bytes)
 447 {
 448   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 449     return NULL;
 450
 451   return g_try_realloc (mem, n_blocks * n_block_bytes);
 452 }
 453
 454 /**
 455  * g_mem_is_system_malloc:
 456  *
 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.
 462  *
 463  * Returns: if %TRUE, malloc() and g_malloc() can be mixed.
 464  *
 465  * Deprecated: 2.46: GLib always uses the system malloc, so this function always
 466  * returns %TRUE.
 467  **/
 468 gboolean
 469 g_mem_is_system_malloc (void)
 470 {
 471   return TRUE;
 472 }
 473
 474 /**
 475  * g_mem_set_vtable:
 476  * @vtable: table of memory allocation routines.
 477  *
 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.
 482  *
 483  * Deprecated: 2.46: This function now does nothing. Use other memory
 484  * profiling tools instead
 485  */
 486 void
 487 g_mem_set_vtable (GMemVTable *vtable)
 488 {
 489   g_warning (G_STRLOC ": custom memory allocation vtable not supported");
 490 }
 491
 492
 493 /**
 494  * glib_mem_profiler_table:
 495  *
 496  * Used to be a #GMemVTable containing profiling variants of the memory
 497  * allocation functions, but this variable shouldn't be modified anymore.
 498  *
 499  * Deprecated: 2.46: Use other memory profiling tools instead
 500  */
 501 GMemVTable *glib_mem_profiler_table = &glib_mem_vtable;
 502
 503 /**
 504  * g_mem_profile:
 505  *
 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.
 509  *
 510  * Deprecated: 2.46: Use other memory profiling tools instead
 511  */
 512 void
 513 g_mem_profile (void)
 514 {
 515   g_warning (G_STRLOC ": memory profiling not supported");
 516 }