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