Gio.Initable

g GObject.GInterface GObject.GInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable

Implementations:
 Gio.CharsetConverter, Gio.DBusConnection, Gio.DBusObjectManagerClient, Gio.DBusProxy, Gio.DBusServer, Gio.InetAddressMask, Gio.Socket, Gio.Subprocess

Methods

class newv (object_type, parameters, cancellable)
  init (cancellable)

Virtual Methods

  do_init (cancellable)

Properties

None

Signals

None

Fields

None

Class Details

class Gio.Initable
Bases:GObject.GInterface
Structure:Gio.InitableIface

Gio.Initable 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 Gio.Initable.init() or Gio.AsyncInitable.init_async() (the latter is only available if it also implements Gio.AsyncInitable).

If the object is not initialized, or initialization returns with an error, then all operations on the object except GObject.Object.ref() and GObject.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 Gio.Initable.init() under the cover, returning None and setting a GLib.Error 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 implemention Gio.Initable during normal construction and automatically initialize them, throwing an exception on failure.

New in version 2.22.

classmethod newv(object_type, parameters, cancellable)[source]
Parameters:
Raises:

GLib.Error

Returns:

a newly allocated GObject.Object, or None on error

Return type:

GObject.Object

Helper function for constructing Gio.Initable object. This is similar to GObject.Object.newv() but also initializes the object and returns None, setting an error on failure.

New in version 2.22.

Deprecated since version 2.54: Use GObject.Object.new() and Gio.Initable.init() instead. See GObject.Parameter for more information.

init(cancellable)[source]
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:GLib.Error
Returns:True if successful. If an error has occurred, this function will return False and set error appropriately if present.
Return type:bool

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 Gio.AsyncInitable.init_async().

Implementations may also support cancellation. If cancellable is not None, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned. If cancellable is not None and the object doesn’t support cancellable initialization the error Gio.IOErrorEnum.NOT_SUPPORTED will be returned.

If the object is not initialized, or initialization returns with an error, then all operations on the object except GObject.Object.ref() and GObject.Object.unref() are considered to be invalid, and have undefined behaviour. See the ‘introduction [ginitable]’ for more details.

Callers should not assume that a class which implements Gio.Initable 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 Gio.Initable 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 GObject.ObjectClass.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call Gio.Initable.init() on the result of GObject.Object.new(), regardless of whether it is in fact a new instance.

New in version 2.22.

do_init(cancellable) virtual
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Returns:True if successful. If an error has occurred, this function will return False and set error appropriately if present.
Return type:bool

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 Gio.AsyncInitable.init_async().

Implementations may also support cancellation. If cancellable is not None, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned. If cancellable is not None and the object doesn’t support cancellable initialization the error Gio.IOErrorEnum.NOT_SUPPORTED will be returned.

If the object is not initialized, or initialization returns with an error, then all operations on the object except GObject.Object.ref() and GObject.Object.unref() are considered to be invalid, and have undefined behaviour. See the ‘introduction [ginitable]’ for more details.

Callers should not assume that a class which implements Gio.Initable 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 Gio.Initable 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 GObject.ObjectClass.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call Gio.Initable.init() on the result of GObject.Object.new(), regardless of whether it is in fact a new instance.

New in version 2.22.