GLib – 2.0: Automatic Cleanup
Description: Reference for GLib-2.0: 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