| Copyright | Will Thompson and Iñaki García Etxebarria |
|---|---|
| License | LGPL-2.1 |
| Maintainer | Iñaki García Etxebarria |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
GI.Gio.Interfaces.Initable
Contents
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 implementing 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
Memory-managed wrapper type.
Constructors
| Initable (ManagedPtr Initable) |
Instances
| Eq Initable Source # | |
| GObject Initable Source # | |
Defined in GI.Gio.Interfaces.Initable | |
| ManagedPtrNewtype Initable Source # | |
Defined in GI.Gio.Interfaces.Initable Methods toManagedPtr :: Initable -> ManagedPtr Initable # | |
| TypedObject Initable Source # | |
Defined in GI.Gio.Interfaces.Initable | |
| HasParentTypes Initable Source # | |
Defined in GI.Gio.Interfaces.Initable | |
| IsGValue (Maybe Initable) Source # | Convert |
Defined in GI.Gio.Interfaces.Initable | |
| type ParentTypes Initable Source # | |
Defined in GI.Gio.Interfaces.Initable | |
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
| (GObject o, IsDescendantOf Initable o) => IsInitable o Source # | |
Defined in GI.Gio.Interfaces.Initable | |
toInitable :: (MonadIO m, IsInitable o) => o -> m Initable Source #
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, init, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.
Getters
getData, getProperty, getQdata.
Setters
init
Arguments
| :: (HasCallStack, MonadIO m, IsInitable a, IsCancellable b) | |
| => a |
|
| -> Maybe b |
|
| -> m () | (Can throw |
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
Arguments
| :: (HasCallStack, MonadIO m, IsCancellable a) | |
| => GType | |
| -> [Parameter] |
|
| -> Maybe a |
|
| -> m Object | Returns: a newly allocated
|
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