Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria
Safe Haskell	None
Language	Haskell2010

GI.Gio.Interfaces.Initable

Contents

Exported types
Methods

Description

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 initableInit or asyncInitableInitAsync (the latter is only available if it also implements AsyncInitable).

If the object is not initialized, or initialization returns with an error, then all operations on the object except objectRef and objectUnref 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 initableInit under the cover, returning Nothing 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 implemention GInitable during normal construction and automatically initialize them, throwing an exception on failure.

Since: 2.22

Synopsis

newtype Initable = Initable (ManagedPtr Initable)
class (GObject o, IsDescendantOf Initable o) => IsInitable o
toInitable :: (MonadIO m, IsInitable o) => o -> m Initable
initableInit :: (HasCallStack, MonadIO m, IsInitable a, IsCancellable b) => a -> Maybe b -> m ()
initableNewv :: (HasCallStack, MonadIO m, IsCancellable a) => GType -> [Parameter] -> Maybe a -> m Object

Exported types

newtype Initable Source #

Memory-managed wrapper type.

Constructors

Initable (ManagedPtr Initable)

Instances

Instances details

Eq Initable Source #
Instance details Defined in GI.Gio.Interfaces.Initable Methods (==) :: Initable -> Initable -> Bool # (/=) :: Initable -> Initable -> Bool #
IsGValue Initable Source #	Convert `Initable` to and from `GValue` with `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Interfaces.Initable Methods toGValue :: Initable -> IO GValue # fromGValue :: GValue -> IO Initable #
ManagedPtrNewtype Initable Source #
Instance details Defined in GI.Gio.Interfaces.Initable Methods toManagedPtr :: Initable -> ManagedPtr Initable #
TypedObject Initable Source #
Instance details Defined in GI.Gio.Interfaces.Initable Methods glibType :: IO GType #
GObject Initable Source #
Instance details Defined in GI.Gio.Interfaces.Initable
HasParentTypes Initable Source #
Instance details Defined in GI.Gio.Interfaces.Initable
type ParentTypes Initable Source #
Instance details Defined in GI.Gio.Interfaces.Initable type ParentTypes Initable = '[Object]

class (GObject o, IsDescendantOf Initable o) => IsInitable o Source #

Type class for types which can be safely cast to Initable, for instance with toInitable.

Instances

Instances details

(GObject o, IsDescendantOf Initable o) => IsInitable o Source #
Instance details Defined in GI.Gio.Interfaces.Initable

toInitable :: (MonadIO m, IsInitable o) => o -> m Initable Source #

Cast to Initable, for types for which this is known to be safe. For general casts, use castTo.

Methods

Overloaded methods

init

initableInit Source #

Arguments

:: (HasCallStack, MonadIO m, IsInitable a, IsCancellable b)
=> a	`initable`: a `Initable`.
-> Maybe b	`cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> m ()	(Can throw `GError`)

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 asyncInitableInitAsync.

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

If the object is not initialized, or initialization returns with an error, then all operations on the object except objectRef and objectUnref 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 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 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 ObjectClass.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call initableInit on the result of g_object_new(), regardless of whether it is in fact a new instance.

Since: 2.22

newv

initableNewv Source #

Arguments

:: (HasCallStack, MonadIO m, IsCancellable a)
=> GType	`objectType`: a `GType` supporting `Initable`.
-> [Parameter]	`parameters`: the parameters to use to construct the object
-> Maybe a	`cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> m Object	Returns: a newly allocated `Object`, or `Nothing` on error (Can throw `GError`)

Deprecated: (Since version 2.54)Use g_object_new_with_properties() andinitableInit instead. See Parameter for more information.

Helper function for constructing Initable object. This is similar to objectNewv but also initializes the object and returns Nothing, setting an error on failure.

Since: 2.22