Branch data Line data Source code
1 : : /* GLIB - Library of useful routines for C programming
2 : : * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3 : : *
4 : : * SPDX-License-Identifier: LGPL-2.1-or-later
5 : : *
6 : : * This library is free software; you can redistribute it and/or
7 : : * modify it under the terms of the GNU Lesser General Public
8 : : * License as published by the Free Software Foundation; either
9 : : * version 2.1 of the License, or (at your option) any later version.
10 : : *
11 : : * This library is distributed in the hope that it will be useful,
12 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 : : * Lesser General Public License for more details.
15 : : *
16 : : * You should have received a copy of the GNU Lesser General Public
17 : : * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 : : */
19 : :
20 : : /*
21 : : * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 : : * file for a list of people on the GLib Team. See the ChangeLog
23 : : * files for a list of changes. These files are distributed with
24 : : * GLib at ftp://ftp.gtk.org/pub/gtk/.
25 : : */
26 : :
27 : : #ifndef __G_MEM_H__
28 : : #define __G_MEM_H__
29 : :
30 : : #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
31 : : #error "Only <glib.h> can be included directly."
32 : : #endif
33 : :
34 : : #include <glib/gutils.h>
35 : : #include <glib/glib-typeof.h>
36 : :
37 : : G_BEGIN_DECLS
38 : :
39 : : /**
40 : : * GMemVTable:
41 : : * @malloc: function to use for allocating memory.
42 : : * @realloc: function to use for reallocating memory.
43 : : * @free: function to use to free memory.
44 : : * @calloc: function to use for allocating zero-filled memory.
45 : : * @try_malloc: function to use for allocating memory without a default error handler.
46 : : * @try_realloc: function to use for reallocating memory without a default error handler.
47 : : *
48 : : * A set of functions used to perform memory allocation. The same #GMemVTable must
49 : : * be used for all allocations in the same program; a call to g_mem_set_vtable(),
50 : : * if it exists, should be prior to any use of GLib.
51 : : *
52 : : * This functions related to this has been deprecated in 2.46, and no longer work.
53 : : */
54 : : typedef struct _GMemVTable GMemVTable;
55 : :
56 : :
57 : : #if GLIB_SIZEOF_VOID_P > GLIB_SIZEOF_LONG
58 : : /**
59 : : * G_MEM_ALIGN:
60 : : *
61 : : * Indicates the number of bytes to which memory will be aligned on the
62 : : * current platform.
63 : : */
64 : : # define G_MEM_ALIGN GLIB_SIZEOF_VOID_P
65 : : #else /* GLIB_SIZEOF_VOID_P <= GLIB_SIZEOF_LONG */
66 : : # define G_MEM_ALIGN GLIB_SIZEOF_LONG
67 : : #endif /* GLIB_SIZEOF_VOID_P <= GLIB_SIZEOF_LONG */
68 : :
69 : :
70 : : /* Memory allocation functions
71 : : */
72 : :
73 : : GLIB_AVAILABLE_IN_ALL
74 : : void (g_free) (gpointer mem);
75 : : GLIB_AVAILABLE_IN_2_76
76 : : void g_free_sized (gpointer mem,
77 : : size_t size);
78 : :
79 : : GLIB_AVAILABLE_IN_2_34
80 : : void g_clear_pointer (gpointer *pp,
81 : : GDestroyNotify destroy);
82 : :
83 : : GLIB_AVAILABLE_IN_ALL
84 : : gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
85 : : GLIB_AVAILABLE_IN_ALL
86 : : gpointer g_malloc0 (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
87 : : GLIB_AVAILABLE_IN_ALL
88 : : gpointer g_realloc (gpointer mem,
89 : : gsize n_bytes) G_GNUC_WARN_UNUSED_RESULT;
90 : : GLIB_AVAILABLE_IN_ALL
91 : : gpointer g_try_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
92 : : GLIB_AVAILABLE_IN_ALL
93 : : gpointer g_try_malloc0 (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
94 : : GLIB_AVAILABLE_IN_ALL
95 : : gpointer g_try_realloc (gpointer mem,
96 : : gsize n_bytes) G_GNUC_WARN_UNUSED_RESULT;
97 : :
98 : : GLIB_AVAILABLE_IN_ALL
99 : : gpointer g_malloc_n (gsize n_blocks,
100 : : gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1,2);
101 : : GLIB_AVAILABLE_IN_ALL
102 : : gpointer g_malloc0_n (gsize n_blocks,
103 : : gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1,2);
104 : : GLIB_AVAILABLE_IN_ALL
105 : : gpointer g_realloc_n (gpointer mem,
106 : : gsize n_blocks,
107 : : gsize n_block_bytes) G_GNUC_WARN_UNUSED_RESULT;
108 : : GLIB_AVAILABLE_IN_ALL
109 : : gpointer g_try_malloc_n (gsize n_blocks,
110 : : gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1,2);
111 : : GLIB_AVAILABLE_IN_ALL
112 : : gpointer g_try_malloc0_n (gsize n_blocks,
113 : : gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1,2);
114 : : GLIB_AVAILABLE_IN_ALL
115 : : gpointer g_try_realloc_n (gpointer mem,
116 : : gsize n_blocks,
117 : : gsize n_block_bytes) G_GNUC_WARN_UNUSED_RESULT;
118 : :
119 : : GLIB_AVAILABLE_IN_2_72
120 : : gpointer g_aligned_alloc (gsize n_blocks,
121 : : gsize n_block_bytes,
122 : : gsize alignment) G_GNUC_WARN_UNUSED_RESULT G_GNUC_ALLOC_SIZE2(1,2);
123 : : GLIB_AVAILABLE_IN_2_72
124 : : gpointer g_aligned_alloc0 (gsize n_blocks,
125 : : gsize n_block_bytes,
126 : : gsize alignment) G_GNUC_WARN_UNUSED_RESULT G_GNUC_ALLOC_SIZE2(1,2);
127 : : GLIB_AVAILABLE_IN_2_72
128 : : void g_aligned_free (gpointer mem);
129 : : GLIB_AVAILABLE_IN_2_76
130 : : void g_aligned_free_sized (gpointer mem,
131 : : size_t alignment,
132 : : size_t size);
133 : :
134 : : #if defined(glib_typeof) && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_58
135 : : #define g_clear_pointer(pp, destroy) \
136 : : G_STMT_START \
137 : : { \
138 : : G_STATIC_ASSERT (sizeof *(pp) == sizeof (gpointer)); \
139 : : glib_typeof ((pp)) _pp = (pp); \
140 : : glib_typeof (*(pp)) _ptr = *_pp; \
141 : : *_pp = NULL; \
142 : : if (_ptr) \
143 : : (destroy) (_ptr); \
144 : : } \
145 : : G_STMT_END \
146 : : GLIB_AVAILABLE_MACRO_IN_2_34
147 : : #else /* __GNUC__ */
148 : : #define g_clear_pointer(pp, destroy) \
149 : : G_STMT_START { \
150 : : G_STATIC_ASSERT (sizeof *(pp) == sizeof (gpointer)); \
151 : : /* Only one access, please; work around type aliasing */ \
152 : : union { char *in; gpointer *out; } _pp; \
153 : : gpointer _p; \
154 : : /* This assignment is needed to avoid a gcc warning */ \
155 : : GDestroyNotify _destroy = (GDestroyNotify) (destroy); \
156 : : \
157 : : _pp.in = (char *) (pp); \
158 : : _p = *_pp.out; \
159 : : if (_p) \
160 : : { \
161 : : *_pp.out = NULL; \
162 : : _destroy (_p); \
163 : : } \
164 : : } G_STMT_END \
165 : : GLIB_AVAILABLE_MACRO_IN_2_34
166 : : #endif /* __GNUC__ */
167 : :
168 : :
169 : : #if G_GNUC_CHECK_VERSION (4, 1) && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_78 && defined(G_HAVE_FREE_SIZED)
170 : :
171 : : #define g_free(mem) \
172 : : (__builtin_object_size ((mem), 0) != ((size_t) - 1)) ? \
173 : : g_free_sized (mem, __builtin_object_size ((mem), 0)) : (g_free) (mem)
174 : :
175 : : #endif /* G_GNUC_CHECK_VERSION (4, 1) && && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_78 && defined(G_HAVE_FREE_SIZED) */
176 : :
177 : : /**
178 : : * g_steal_pointer:
179 : : * @pp: (not nullable): a pointer to a pointer
180 : : *
181 : : * Sets @pp to %NULL, returning the value that was there before.
182 : : *
183 : : * Conceptually, this transfers the ownership of the pointer from the
184 : : * referenced variable to the "caller" of the macro (ie: "steals" the
185 : : * reference).
186 : : *
187 : : * The return value will be properly typed, according to the type of
188 : : * @pp.
189 : : *
190 : : * This can be very useful when combined with g_autoptr() to prevent the
191 : : * return value of a function from being automatically freed. Consider
192 : : * the following example (which only works on GCC and clang):
193 : : *
194 : : * |[
195 : : * GObject *
196 : : * create_object (void)
197 : : * {
198 : : * g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
199 : : *
200 : : * if (early_error_case)
201 : : * return NULL;
202 : : *
203 : : * return g_steal_pointer (&obj);
204 : : * }
205 : : * ]|
206 : : *
207 : : * It can also be used in similar ways for 'out' parameters and is
208 : : * particularly useful for dealing with optional out parameters:
209 : : *
210 : : * |[
211 : : * gboolean
212 : : * get_object (GObject **obj_out)
213 : : * {
214 : : * g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
215 : : *
216 : : * if (early_error_case)
217 : : * return FALSE;
218 : : *
219 : : * if (obj_out)
220 : : * *obj_out = g_steal_pointer (&obj);
221 : : *
222 : : * return TRUE;
223 : : * }
224 : : * ]|
225 : : *
226 : : * In the above example, the object will be automatically freed in the
227 : : * early error case and also in the case that %NULL was given for
228 : : * @obj_out.
229 : : *
230 : : * Since: 2.44
231 : : */
232 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_44
233 : : static inline gpointer
234 : 3739685 : g_steal_pointer (gpointer pp)
235 : : {
236 : 3739685 : gpointer *ptr = (gpointer *) pp;
237 : : gpointer ref;
238 : :
239 : 3739685 : ref = *ptr;
240 : 3739685 : *ptr = NULL;
241 : :
242 : 3739685 : return ref;
243 : : }
244 : :
245 : : /* type safety */
246 : : #if defined(glib_typeof) && GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_58
247 : : #define g_steal_pointer(pp) ((glib_typeof (*pp)) (g_steal_pointer) (pp))
248 : : #else /* __GNUC__ */
249 : : /* This version does not depend on gcc extensions, but gcc does not warn
250 : : * about incompatible-pointer-types: */
251 : : #define g_steal_pointer(pp) \
252 : : (0 ? (*(pp)) : (g_steal_pointer) (pp))
253 : : #endif /* __GNUC__ */
254 : :
255 : : /* Optimise: avoid the call to the (slower) _n function if we can
256 : : * determine at compile-time that no overflow happens.
257 : : */
258 : : #if defined (__GNUC__) && (__GNUC__ >= 2) && defined (__OPTIMIZE__)
259 : : # define _G_NEW(struct_type, n_structs, func) \
260 : : (struct_type *) (G_GNUC_EXTENSION ({ \
261 : : gsize __n = (gsize) (n_structs); \
262 : : gsize __s = sizeof (struct_type); \
263 : : gpointer __p; \
264 : : if (__s == 1) \
265 : : __p = g_##func (__n); \
266 : : else if (__builtin_constant_p (__n) && \
267 : : (__s == 0 || __n <= G_MAXSIZE / __s)) \
268 : : __p = g_##func (__n * __s); \
269 : : else \
270 : : __p = g_##func##_n (__n, __s); \
271 : : __p; \
272 : : }))
273 : : # define _G_RENEW(struct_type, mem, n_structs, func) \
274 : : (struct_type *) (G_GNUC_EXTENSION ({ \
275 : : gsize __n = (gsize) (n_structs); \
276 : : gsize __s = sizeof (struct_type); \
277 : : gpointer __p = (gpointer) (mem); \
278 : : if (__s == 1) \
279 : : __p = g_##func (__p, __n); \
280 : : else if (__builtin_constant_p (__n) && \
281 : : (__s == 0 || __n <= G_MAXSIZE / __s)) \
282 : : __p = g_##func (__p, __n * __s); \
283 : : else \
284 : : __p = g_##func##_n (__p, __n, __s); \
285 : : __p; \
286 : : }))
287 : :
288 : : #else
289 : :
290 : : /* Unoptimised version: always call the _n() function. */
291 : :
292 : : #define _G_NEW(struct_type, n_structs, func) \
293 : : ((struct_type *) g_##func##_n ((n_structs), sizeof (struct_type)))
294 : : #define _G_RENEW(struct_type, mem, n_structs, func) \
295 : : ((struct_type *) g_##func##_n (mem, (n_structs), sizeof (struct_type)))
296 : :
297 : : #endif
298 : :
299 : : /**
300 : : * g_new:
301 : : * @struct_type: the type of the elements to allocate
302 : : * @n_structs: the number of elements to allocate
303 : : *
304 : : * Allocates @n_structs elements of type @struct_type.
305 : : * The returned pointer is cast to a pointer to the given type.
306 : : * If @n_structs is 0 it returns %NULL.
307 : : * Care is taken to avoid overflow when calculating the size of the allocated block.
308 : : *
309 : : * Since the returned pointer is already casted to the right type,
310 : : * it is normally unnecessary to cast it explicitly, and doing
311 : : * so might hide memory allocation errors.
312 : : *
313 : : * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
314 : : */
315 : : #define g_new(struct_type, n_structs) _G_NEW (struct_type, n_structs, malloc)
316 : : /**
317 : : * g_new0:
318 : : * @struct_type: the type of the elements to allocate.
319 : : * @n_structs: the number of elements to allocate.
320 : : *
321 : : * Allocates @n_structs elements of type @struct_type, initialized to 0's.
322 : : * The returned pointer is cast to a pointer to the given type.
323 : : * If @n_structs is 0 it returns %NULL.
324 : : * Care is taken to avoid overflow when calculating the size of the allocated block.
325 : : *
326 : : * Since the returned pointer is already casted to the right type,
327 : : * it is normally unnecessary to cast it explicitly, and doing
328 : : * so might hide memory allocation errors.
329 : : *
330 : : * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
331 : : */
332 : : #define g_new0(struct_type, n_structs) _G_NEW (struct_type, n_structs, malloc0)
333 : : /**
334 : : * g_renew:
335 : : * @struct_type: the type of the elements to allocate
336 : : * @mem: the currently allocated memory
337 : : * @n_structs: the number of elements to allocate
338 : : *
339 : : * Reallocates the memory pointed to by @mem, so that it now has space for
340 : : * @n_structs elements of type @struct_type. It returns the new address of
341 : : * the memory, which may have been moved.
342 : : * Care is taken to avoid overflow when calculating the size of the allocated block.
343 : : *
344 : : * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
345 : : */
346 : : #define g_renew(struct_type, mem, n_structs) _G_RENEW (struct_type, mem, n_structs, realloc)
347 : : /**
348 : : * g_try_new:
349 : : * @struct_type: the type of the elements to allocate
350 : : * @n_structs: the number of elements to allocate
351 : : *
352 : : * Attempts to allocate @n_structs elements of type @struct_type, and returns
353 : : * %NULL on failure. Contrast with g_new(), which aborts the program on failure.
354 : : * The returned pointer is cast to a pointer to the given type.
355 : : * The function returns %NULL when @n_structs is 0 of if an overflow occurs.
356 : : *
357 : : * Since: 2.8
358 : : * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
359 : : */
360 : : #define g_try_new(struct_type, n_structs) _G_NEW (struct_type, n_structs, try_malloc)
361 : : /**
362 : : * g_try_new0:
363 : : * @struct_type: the type of the elements to allocate
364 : : * @n_structs: the number of elements to allocate
365 : : *
366 : : * Attempts to allocate @n_structs elements of type @struct_type, initialized
367 : : * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
368 : : * the program on failure.
369 : : * The returned pointer is cast to a pointer to the given type.
370 : : * The function returns %NULL when @n_structs is 0 or if an overflow occurs.
371 : : *
372 : : * Since: 2.8
373 : : * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
374 : : */
375 : : #define g_try_new0(struct_type, n_structs) _G_NEW (struct_type, n_structs, try_malloc0)
376 : : /**
377 : : * g_try_renew:
378 : : * @struct_type: the type of the elements to allocate
379 : : * @mem: the currently allocated memory
380 : : * @n_structs: the number of elements to allocate
381 : : *
382 : : * Attempts to reallocate the memory pointed to by @mem, so that it now has
383 : : * space for @n_structs elements of type @struct_type, and returns %NULL on
384 : : * failure. Contrast with g_renew(), which aborts the program on failure.
385 : : * It returns the new address of the memory, which may have been moved.
386 : : * The function returns %NULL if an overflow occurs.
387 : : *
388 : : * Since: 2.8
389 : : * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
390 : : */
391 : : #define g_try_renew(struct_type, mem, n_structs) _G_RENEW (struct_type, mem, n_structs, try_realloc)
392 : :
393 : :
394 : : /* Memory allocation virtualization for debugging purposes
395 : : * g_mem_set_vtable() has to be the very first GLib function called
396 : : * if being used
397 : : */
398 : : struct _GMemVTable {
399 : : gpointer (*malloc) (gsize n_bytes);
400 : : gpointer (*realloc) (gpointer mem,
401 : : gsize n_bytes);
402 : : void (*free) (gpointer mem);
403 : : /* optional; set to NULL if not used ! */
404 : : gpointer (*calloc) (gsize n_blocks,
405 : : gsize n_block_bytes);
406 : : gpointer (*try_malloc) (gsize n_bytes);
407 : : gpointer (*try_realloc) (gpointer mem,
408 : : gsize n_bytes);
409 : : };
410 : : GLIB_DEPRECATED_IN_2_46
411 : : void g_mem_set_vtable (GMemVTable *vtable);
412 : : GLIB_DEPRECATED_IN_2_46
413 : : gboolean g_mem_is_system_malloc (void);
414 : :
415 : : GLIB_VAR gboolean g_mem_gc_friendly;
416 : :
417 : : /* Memory profiler and checker, has to be enabled via g_mem_set_vtable()
418 : : */
419 : : GLIB_VAR GMemVTable *glib_mem_profiler_table;
420 : : GLIB_DEPRECATED_IN_2_46
421 : : void g_mem_profile (void);
422 : :
423 : : G_END_DECLS
424 : :
425 : : #endif /* __G_MEM_H__ */
|
