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 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 fails, the application is terminated.
  67  * This also means that there is no need to check if the call succeeded.
  68  *
  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).
  75  */
  76
  77 /* --- functions --- */
  78 /**
  79  * g_malloc:
  80  * @n_bytes: the number of bytes to allocate
  81  *
  82  * Allocates @n_bytes bytes of memory.
  83  * If @n_bytes is 0 it returns %NULL.
  84  *
  85  * Returns: a pointer to the allocated memory
  86  */
  87 gpointer
  88 g_malloc (gsize n_bytes)
  89 {
  90   if (G_LIKELY (n_bytes))
  91     {
  92       gpointer mem;
  93
  94       mem = malloc (n_bytes);
  95       TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 0));
  96       if (mem)
  97         return mem;
  98
  99       g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
 100                G_STRLOC, n_bytes);
 101     }
 102
 103   TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 0, 0));
 104
 105   return NULL;
 106 }
 107
 108 /**
 109  * g_malloc0:
 110  * @n_bytes: the number of bytes to allocate
 111  *
 112  * Allocates @n_bytes bytes of memory, initialized to 0's.
 113  * If @n_bytes is 0 it returns %NULL.
 114  *
 115  * Returns: a pointer to the allocated memory
 116  */
 117 gpointer
 118 g_malloc0 (gsize n_bytes)
 119 {
 120   if (G_LIKELY (n_bytes))
 121     {
 122       gpointer mem;
 123
 124       mem = calloc (1, n_bytes);
 125       TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 1, 0));
 126       if (mem)
 127         return mem;
 128
 129       g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
 130                G_STRLOC, n_bytes);
 131     }
 132
 133   TRACE(GLIB_MEM_ALLOC((void*) NULL, (int) n_bytes, 1, 0));
 134
 135   return NULL;
 136 }
 137
 138 /**
 139  * g_realloc:
 140  * @mem: (nullable): the memory to reallocate
 141  * @n_bytes: new size of the memory in bytes
 142  *
 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.
 148  *
 149  * Returns: the new address of the allocated memory
 150  */
 151 gpointer
 152 g_realloc (gpointer mem,
 153            gsize    n_bytes)
 154 {
 155   gpointer newmem;
 156
 157   if (G_LIKELY (n_bytes))
 158     {
 159       newmem = realloc (mem, n_bytes);
 160       TRACE (GLIB_MEM_REALLOC((void*) newmem, (void*)mem, (unsigned int) n_bytes, 0));
 161       if (newmem)
 162         return newmem;
 163
 164       g_error ("%s: failed to allocate %"G_GSIZE_FORMAT" bytes",
 165                G_STRLOC, n_bytes);
 166     }
 167
 168   if (mem)
 169     free (mem);
 170
 171   TRACE (GLIB_MEM_REALLOC((void*) NULL, (void*)mem, 0, 0));
 172
 173   return NULL;
 174 }
 175
 176 /**
 177  * g_free:
 178  * @mem: (nullable): the memory to free
 179  *
 180  * Frees the memory pointed to by @mem.
 181  *
 182  * If @mem is %NULL it simply returns, so there is no need to check @mem
 183  * against %NULL before calling this function.
 184  */
 185 void
 186 g_free (gpointer mem)
 187 {
 188   if (G_LIKELY (mem))
 189     free (mem);
 190   TRACE(GLIB_MEM_FREE((void*) mem));
 191 }
 192
 193 /**
 194  * g_clear_pointer: (skip)
 195  * @pp: (not nullable): a pointer to a variable, struct member etc. holding a
 196  *    pointer
 197  * @destroy: a function to which a gpointer can be passed, to destroy *@pp
 198  *
 199  * Clears a reference to a variable.
 200  *
 201  * @pp must not be %NULL.
 202  *
 203  * If the reference is %NULL then this function does nothing.
 204  * Otherwise, the variable is destroyed using @destroy and the
 205  * pointer is set to %NULL.
 206  *
 207  * A macro is also included that allows this function to be used without
 208  * pointer casts.
 209  *
 210  * Since: 2.34
 211  **/
 212 #undef g_clear_pointer
 213 void
 214 g_clear_pointer (gpointer      *pp,
 215                  GDestroyNotify destroy)
 216 {
 217   gpointer _p;
 218
 219   _p = *pp;
 220   if (_p)
 221     {
 222       *pp = NULL;
 223       destroy (_p);
 224     }
 225 }
 226
 227 /**
 228  * g_try_malloc:
 229  * @n_bytes: number of bytes to allocate.
 230  *
 231  * Attempts to allocate @n_bytes, and returns %NULL on failure.
 232  * Contrast with g_malloc(), which aborts the program on failure.
 233  *
 234  * Returns: the allocated memory, or %NULL.
 235  */
 236 gpointer
 237 g_try_malloc (gsize n_bytes)
 238 {
 239   gpointer mem;
 240
 241   if (G_LIKELY (n_bytes))
 242     mem = malloc (n_bytes);
 243   else
 244     mem = NULL;
 245
 246   TRACE (GLIB_MEM_ALLOC((void*) mem, (unsigned int) n_bytes, 0, 1));
 247
 248   return mem;
 249 }
 250
 251 /**
 252  * g_try_malloc0:
 253  * @n_bytes: number of bytes to allocate
 254  *
 255  * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
 256  * failure. Contrast with g_malloc0(), which aborts the program on failure.
 257  *
 258  * Since: 2.8
 259  * Returns: the allocated memory, or %NULL
 260  */
 261 gpointer
 262 g_try_malloc0 (gsize n_bytes)
 263 {
 264   gpointer mem;
 265
 266   if (G_LIKELY (n_bytes))
 267     mem = calloc (1, n_bytes);
 268   else
 269     mem = NULL;
 270
 271   return mem;
 272 }
 273
 274 /**
 275  * g_try_realloc:
 276  * @mem: (nullable): previously-allocated memory, or %NULL.
 277  * @n_bytes: number of bytes to allocate.
 278  *
 279  * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
 280  * on failure. Contrast with g_realloc(), which aborts the program
 281  * on failure.
 282  *
 283  * If @mem is %NULL, behaves the same as g_try_malloc().
 284  *
 285  * Returns: the allocated memory, or %NULL.
 286  */
 287 gpointer
 288 g_try_realloc (gpointer mem,
 289                gsize    n_bytes)
 290 {
 291   gpointer newmem;
 292
 293   if (G_LIKELY (n_bytes))
 294     newmem = realloc (mem, n_bytes);
 295   else
 296     {
 297       newmem = NULL;
 298       if (mem)
 299         free (mem);
 300     }
 301
 302   TRACE (GLIB_MEM_REALLOC((void*) newmem, (void*)mem, (unsigned int) n_bytes, 1));
 303
 304   return newmem;
 305 }
 306
 307
 308 #define SIZE_OVERFLOWS(a,b) (G_UNLIKELY ((b) > 0 && (a) > G_MAXSIZE / (b)))
 309
 310 /**
 311  * g_malloc_n:
 312  * @n_blocks: the number of blocks to allocate
 313  * @n_block_bytes: the size of each block in bytes
 314  *
 315  * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 316  * but care is taken to detect possible overflow during multiplication.
 317  *
 318  * Since: 2.24
 319  * Returns: a pointer to the allocated memory
 320  */
 321 gpointer
 322 g_malloc_n (gsize n_blocks,
 323             gsize n_block_bytes)
 324 {
 325   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 326     {
 327       g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
 328                G_STRLOC, n_blocks, n_block_bytes);
 329     }
 330
 331   return g_malloc (n_blocks * n_block_bytes);
 332 }
 333
 334 /**
 335  * g_malloc0_n:
 336  * @n_blocks: the number of blocks to allocate
 337  * @n_block_bytes: the size of each block in bytes
 338  *
 339  * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
 340  * but care is taken to detect possible overflow during multiplication.
 341  *
 342  * Since: 2.24
 343  * Returns: a pointer to the allocated memory
 344  */
 345 gpointer
 346 g_malloc0_n (gsize n_blocks,
 347              gsize n_block_bytes)
 348 {
 349   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 350     {
 351       g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
 352                G_STRLOC, n_blocks, n_block_bytes);
 353     }
 354
 355   return g_malloc0 (n_blocks * n_block_bytes);
 356 }
 357
 358 /**
 359  * g_realloc_n:
 360  * @mem: (nullable): the memory to reallocate
 361  * @n_blocks: the number of blocks to allocate
 362  * @n_block_bytes: the size of each block in bytes
 363  *
 364  * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 365  * but care is taken to detect possible overflow during multiplication.
 366  *
 367  * Since: 2.24
 368  * Returns: the new address of the allocated memory
 369  */
 370 gpointer
 371 g_realloc_n (gpointer mem,
 372              gsize    n_blocks,
 373              gsize    n_block_bytes)
 374 {
 375   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 376     {
 377       g_error ("%s: overflow allocating %"G_GSIZE_FORMAT"*%"G_GSIZE_FORMAT" bytes",
 378                G_STRLOC, n_blocks, n_block_bytes);
 379     }
 380
 381   return g_realloc (mem, n_blocks * n_block_bytes);
 382 }
 383
 384 /**
 385  * g_try_malloc_n:
 386  * @n_blocks: the number of blocks to allocate
 387  * @n_block_bytes: the size of each block in bytes
 388  *
 389  * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 390  * but care is taken to detect possible overflow during multiplication.
 391  *
 392  * Since: 2.24
 393  * Returns: the allocated memory, or %NULL.
 394  */
 395 gpointer
 396 g_try_malloc_n (gsize n_blocks,
 397                 gsize n_block_bytes)
 398 {
 399   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 400     return NULL;
 401
 402   return g_try_malloc (n_blocks * n_block_bytes);
 403 }
 404
 405 /**
 406  * g_try_malloc0_n:
 407  * @n_blocks: the number of blocks to allocate
 408  * @n_block_bytes: the size of each block in bytes
 409  *
 410  * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
 411  * but care is taken to detect possible overflow during multiplication.
 412  *
 413  * Since: 2.24
 414  * Returns: the allocated memory, or %NULL
 415  */
 416 gpointer
 417 g_try_malloc0_n (gsize n_blocks,
 418                  gsize n_block_bytes)
 419 {
 420   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 421     return NULL;
 422
 423   return g_try_malloc0 (n_blocks * n_block_bytes);
 424 }
 425
 426 /**
 427  * g_try_realloc_n:
 428  * @mem: (nullable): previously-allocated memory, or %NULL.
 429  * @n_blocks: the number of blocks to allocate
 430  * @n_block_bytes: the size of each block in bytes
 431  *
 432  * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 433  * but care is taken to detect possible overflow during multiplication.
 434  *
 435  * Since: 2.24
 436  * Returns: the allocated memory, or %NULL.
 437  */
 438 gpointer
 439 g_try_realloc_n (gpointer mem,
 440                  gsize    n_blocks,
 441                  gsize    n_block_bytes)
 442 {
 443   if (SIZE_OVERFLOWS (n_blocks, n_block_bytes))
 444     return NULL;
 445
 446   return g_try_realloc (mem, n_blocks * n_block_bytes);
 447 }
 448
 449 /**
 450  * g_mem_is_system_malloc:
 451  *
 452  * Checks whether the allocator used by g_malloc() is the system's
 453  * malloc implementation. If it returns %TRUE memory allocated with
 454  * malloc() can be used interchangeable with memory allocated using g_malloc().
 455  * This function is useful for avoiding an extra copy of allocated memory returned
 456  * by a non-GLib-based API.
 457  *
 458  * Returns: if %TRUE, malloc() and g_malloc() can be mixed.
 459  *
 460  * Deprecated: 2.46: GLib always uses the system malloc, so this function always
 461  * returns %TRUE.
 462  **/
 463 gboolean
 464 g_mem_is_system_malloc (void)
 465 {
 466   return TRUE;
 467 }
 468
 469 /**
 470  * g_mem_set_vtable:
 471  * @vtable: table of memory allocation routines.
 472  *
 473  * This function used to let you override the memory allocation function.
 474  * However, its use was incompatible with the use of global constructors
 475  * in GLib and GIO, because those use the GLib allocators before main is
 476  * reached. Therefore this function is now deprecated and is just a stub.
 477  *
 478  * Deprecated: 2.46: Use other memory profiling tools instead
 479  */
 480 void
 481 g_mem_set_vtable (GMemVTable *vtable)
 482 {
 483   g_warning (G_STRLOC ": custom memory allocation vtable not supported");
 484 }
 485
 486
 487 /**
 488  * glib_mem_profiler_table:
 489  *
 490  * Used to be a #GMemVTable containing profiling variants of the memory
 491  * allocation functions, but this variable shouldn't be modified anymore.
 492  *
 493  * Deprecated: 2.46: Use other memory profiling tools instead
 494  */
 495 GMemVTable *glib_mem_profiler_table = &glib_mem_vtable;
 496
 497 /**
 498  * g_mem_profile:
 499  *
 500  * GLib used to support some tools for memory profiling, but this
 501  * no longer works. There are many other useful tools for memory
 502  * profiling these days which can be used instead.
 503  *
 504  * Deprecated: 2.46: Use other memory profiling tools instead
 505  */
 506 void
 507 g_mem_profile (void)
 508 {
 509   g_warning (G_STRLOC ": memory profiling not supported");
 510 }