Automatic Cleanup

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