GInitable: GIO Reference Manual

## GInitable GInitable — Failable object initialization interface |

## Functions

gboolean | g_initable_init ()
gpointer | g_initable_new ()
GObject * | g_initable_new_valist ()
gpointer | g_initable_newv ()

## Types and Values

| GInitable
struct | GInitableIface

## Object Hierarchy

        GInterface
        ╰── GInitable

## Prerequisites

GInitable requires GObject.

## Known Derived Interfaces

GInitable is required by GMemoryMonitor, GNetworkMonitor and GPowerProfileMonitor.

## Known Implementations

GInitable is implemented by GCharsetConverter, GDBusConnection, GDBusObjectManagerClient, GDBusProxy, GDBusServer, GInetAddressMask, GSocket and GSubprocess.

## Includes

    #include <gio/gio.h>

## Description

GInitable is implemented by objects that can fail during initialization. If an object implements this interface then it must be initialized as the first thing after construction, either via `g_initable_init()` or `g_async_initable_init_async()` (the latter is only available if it also implements GAsyncInitable).

If the object is not initialized, or initialization returns with an error, then all operations on the object except `g_object_ref()` and `g_object_unref()` are considered to be invalid, and have undefined behaviour. They will often fail with `g_critical()` or `g_warning()`, but this must not be relied on.

Users of objects implementing this are not intended to use the interface method directly, instead it will be used automatically in various ways. For C applications you generally just call `g_initable_new()` directly, or indirectly via a `foo_thing_new()` wrapper. This will call `g_initable_init()` under the cover, returning `NULL` and setting a GError on failure (at which point the instance is unreferenced).

For bindings in languages where the native constructor supports exceptions the binding could check for objects implementing `GInitable` during normal construction and automatically initialize them, throwing an exception on failure.

## Functions

### g_initable_init ()

    gboolean
    g_initable_init (GInitable *initable,
                     GCancellable *cancellable,
                     GError **error);

Initializes the object implementing the interface.

This method is intended for language bindings. If writing in C, `g_initable_new()` should typically be used instead.

The object must be initialized before any real use after initial construction, either with this function or `g_async_initable_init_async()`.

Implementations may also support cancellation. If `cancellable` is not `NULL`, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned. If `cancellable` is not `NULL` and the object doesn't support cancellable initialization the error `G_IO_ERROR_NOT_SUPPORTED` will be returned.

If the object is not initialized, or initialization returns with an error, then all operations on the object except `g_object_ref()` and `g_object_unref()` are considered to be invalid, and have undefined behaviour. See the introduction for more details.

Callers should not assume that a class which implements GInitable can be initialized multiple times, unless the class explicitly documents itself as supporting this. Generally, a class’ implementation of `init()` can assume (and assert) that it will only be called once. Previously, this documentation recommended all GInitable implementations should be idempotent; that recommendation was relaxed in GLib 2.54.

If a class explicitly supports being initialized multiple times, it is recommended that the method is idempotent: multiple calls with the same arguments should return the same results. Only the first call initializes the object; further calls return the result of the first call.

One reason why a class might need to support idempotent initialization is if it is designed to be used via the singleton pattern, with a GObjectClass.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call `g_initable_init()` on the result of `g_object_new()`, regardless of whether it is in fact a new instance.

#### Parameters

initable | a GInitable. |
cancellable | optional GCancellable object, `NULL` to ignore. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` if successful. If an error has occurred, this function will return `FALSE` and set `error` appropriately if present.

Since: 2.22

### g_initable_new ()

    gpointer
    g_initable_new (GType object_type,
                    GCancellable *cancellable,
                    GError **error,
                    const gchar *first_property_name,
                    ...);

Helper function for constructing GInitable object. This is similar to `g_object_new()` but also initializes the object and returns `NULL`, setting an error on failure.

#### Parameters

object_type | a GType supporting GInitable. |
cancellable | optional GCancellable object, `NULL` to ignore. |
error | a GError location to store the error occurring, or `NULL` to ignore. |
first_property_name | the name of the first property, or `NULL` if no properties. | [nullable]
... | the value if the first property, followed by and other property value pairs, and ended by `NULL`. |

#### Returns

a newly allocated GObject, or `NULL` on error.

[type GObject.Object][transfer full]

Since: 2.22

### g_initable_new_valist ()

    GObject *
    g_initable_new_valist (GType object_type,
                           const gchar *first_property_name,
                           va_list var_args,
                           GCancellable *cancellable,
                           GError **error);

Helper function for constructing GInitable object. This is similar to `g_object_new_valist()` but also initializes the object and returns `NULL`, setting an error on failure.

#### Parameters

object_type | a GType supporting GInitable. |
first_property_name | the name of the first property, followed by the value, and other property value pairs, and ended by `NULL`. |
var_args | The var args list generated from `first_property_name` . |
cancellable | optional GCancellable object, `NULL` to ignore. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a newly allocated GObject, or `NULL` on error.

[type GObject.Object][transfer full]

Since: 2.22

### g_initable_newv ()

    gpointer
    g_initable_newv (GType object_type,
                     guint n_parameters,
                     GParameter *parameters,
                     GCancellable *cancellable,
                     GError **error);

`g_initable_newv` has been deprecated since version 2.54 and should not be used in newly-written code.

Use `g_object_new_with_properties()` and `g_initable_init()` instead. See GParameter for more information.

Helper function for constructing GInitable object. This is similar to `g_object_newv()` but also initializes the object and returns `NULL`, setting an error on failure.

#### Parameters

object_type | a GType supporting GInitable. |
n_parameters | the number of parameters in `parameters` |
parameters | the parameters to use to construct the object. | [array length=n_parameters]
cancellable | optional GCancellable object, `NULL` to ignore. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a newly allocated GObject, or `NULL` on error.

[type GObject.Object][transfer full]

Since: 2.22

## Types and Values

### GInitable

    typedef struct _GInitable GInitable;

Interface for initializable objects.

Since: 2.22

### struct GInitableIface

    struct GInitableIface {
      GTypeInterface g_iface;

      /* Virtual Table */

      gboolean    (* init) (GInitable    *initable,
    			GCancellable *cancellable,
    			GError      **error);
    };

Provides an interface for initializing object such that initialization may fail.

#### Members

`init` () | Initializes the object. |

Since: 2.22

## See Also

GAsyncInitable