1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
Title: Automatic Cleanup
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2023 Matthias Clasen
# Automatic Cleanup
GLib provides a set of macros that wrap the GCC extension for automatic
cleanup of variables when they go out of scope.
These macros can only be used with GCC and GCC-compatible C compilers.
## Variable declaration
`g_auto(TypeName)`
: Helper to declare a variable with automatic cleanup.
The variable is cleaned up in a way appropriate to its type when the
variable goes out of scope. The `TypeName` of the variable must support
this.
The way to clean up the type must have been defined using one of the macros
`G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC()` or `G_DEFINE_AUTO_CLEANUP_FREE_FUNC()`.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This macro meant to be used with stack-allocated structures and
non-pointer types. For the (more commonly used) pointer version, see
`g_autoptr()`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
Consider the following example:
GVariant *
my_func(void)
{
g_auto(GQueue) queue = G_QUEUE_INIT;
g_auto(GVariantBuilder) builder;
g_auto(GStrv) strv;
g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
strv = g_strsplit("a:b:c", ":", -1);
// ...
if (error_condition)
return NULL;
// ...
return g_variant_builder_end (&builder);
}
You must initialize the variable in some way — either by use of an
initialiser or by ensuring that an `_init` function will be called on
it unconditionally before it goes out of scope.
Since: 2.44
`g_autoptr(TypeName)`
: Helper to declare a pointer variable with automatic cleanup.
The variable is cleaned up in a way appropriate to its type when the
variable goes out of scope. The `TypeName` of the variable must support this.
The way to clean up the type must have been defined using the macro
`G_DEFINE_AUTOPTR_CLEANUP_FUNC()`.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare pointers to types with cleanup
functions. The type of the variable is a pointer to `TypeName`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
Consider the following example:
gboolean
check_exists(GVariant *dict)
{
g_autoptr(GVariant) dirname, basename = NULL;
g_autofree gchar *path = NULL;
dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
if (dirname == NULL)
return FALSE;
basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
if (basename == NULL)
return FALSE;
path = g_build_filename (g_variant_get_string (dirname, NULL),
g_variant_get_string (basename, NULL),
NULL);
return g_access (path, R_OK) == 0;
}
You must initialise the variable in some way — either by use of an
initialiser or by ensuring that it is assigned to unconditionally
before it goes out of scope.
See also: `g_auto()`, `g_autofree()` and `g_steal_pointer()`.
Since: 2.44
`g_autofree`
: Macro to add an attribute to pointer variable to ensure automatic
cleanup using `g_free()`.
This macro differs from `g_autoptr()` in that it is an attribute supplied
before the type name, rather than wrapping the type definition. Instead
of using a type-specific lookup, this macro always calls `g_free()` directly.
This means it's useful for any type that is returned from `g_malloc()`.
Otherwise, this macro has similar constraints as `g_autoptr()`: only
supported on GCC and clang, the variable must be initialized, etc.
gboolean
operate_on_malloc_buf (void)
{
g_autofree guint8* membuf = NULL;
membuf = g_malloc (8192);
// Some computation on membuf
// membuf will be automatically freed here
return TRUE;
}
Since: 2.44
`g_autolist(TypeName)`
: Helper to declare a list variable with automatic deep cleanup.
The list is deeply freed, in a way appropriate to the specified type, when the
variable goes out of scope. The type must support this.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare lists of a type with a cleanup
function. The type of the variable is a `GList *`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
See also: `g_autoslist()`, `g_autoptr()` and `g_steal_pointer()`.
Since: 2.56
`g_autoslist(TypeName)`
: Helper to declare a singly linked list variable with automatic deep cleanup.
The list is deeply freed, in a way appropriate to the specified type, when the
variable goes out of scope. The type must support this.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare lists of a type with a cleanup
function. The type of the variable is a `GSList *`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
See also: `g_autolist()`, `g_autoptr()` and `g_steal_pointer()`.
Since: 2.56
`g_autoqueue(TypeName)`
: Helper to declare a double-ended queue variable with automatic deep cleanup.
The queue is deeply freed, in a way appropriate to the specified type, when the
variable goes out of scope. The type must support this.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare queues of a type with a cleanup
function. The type of the variable is a `GQueue *`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
See also: `g_autolist()`, `g_autoptr()` and `g_steal_pointer()`.
Since: 2.62
## Type definition
`G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func)`
: Defines the appropriate cleanup function for a pointer type.
The function will not be called if the variable to be cleaned up
contains `NULL`.
This will typically be the `_free()` or `_unref()` function for the given
type.
With this definition, it will be possible to use `g_autoptr()` with
the given `TypeName`.
G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
This macro should be used unconditionally; it is a no-op on compilers
where cleanup is not supported.
Since: 2.44
`G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func)`
: Defines the appropriate cleanup function for a type.
This will typically be the `_clear()` function for the given type.
With this definition, it will be possible to use `g_auto()` with
the given `TypeName`.
G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
This macro should be used unconditionally; it is a no-op on compilers
where cleanup is not supported.
Since: 2.44
`G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none_value)`
: Defines the appropriate cleanup function for a type.
With this definition, it will be possible to use `g_auto()` with the
given `TypeName`.
This function will be rarely used. It is used with pointer-based
typedefs and non-pointer types where the value of the variable
represents a resource that must be freed. Two examples are `GStrv`
and file descriptors.
`none_value` specifies the "none" value for the type in question. It
is probably something like `NULL` or `-1`.If the variable is found to
contain this value then the free function will not be called.
G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
This macro should be used unconditionally; it is a no-op on compilers
where cleanup is not supported.
Since: 2.44
|
