gi-gio-2.0.19: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.Gio.Interfaces.Initable

Contents

- Exported types
- Methods
  - init
  - newv

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)
- noInitable :: Maybe Initable
- class GObject 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

GObject Initable Source # |
Instance details Defined in GI.Gio.Interfaces.Initable Methods gobjectType :: Initable -> IO GType Source #
IsObject Initable Source # |
Instance details Defined in GI.Gio.Interfaces.Initable
IsInitable Initable Source # |
Instance details Defined in GI.Gio.Interfaces.Initable

noInitable :: Maybe Initable Source #

A convenience alias for `Nothing` :: `Maybe` `Initable`.

class GObject o => IsInitable o Source #

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

Instances

(GObject a, (UnknownAncestorError Initable a :: Constraint)) => IsInitable a Source # |
Instance details Defined in GI.Gio.Interfaces.Initable
IsInitable Initable Source # |
Instance details Defined in GI.Gio.Interfaces.Initable
IsInitable CharsetConverter Source # |
Instance details Defined in GI.Gio.Objects.CharsetConverter
IsInitable DBusConnection Source # |
Instance details Defined in GI.Gio.Objects.DBusConnection
IsInitable DBusObjectManagerClient Source # |
Instance details Defined in GI.Gio.Objects.DBusObjectManagerClient
IsInitable DBusProxy Source # |
Instance details Defined in GI.Gio.Objects.DBusProxy
IsInitable DBusServer Source # |
Instance details Defined in GI.Gio.Objects.DBusServer
IsInitable InetAddressMask Source # |
Instance details Defined in GI.Gio.Objects.InetAddressMask
IsInitable Socket Source # |
Instance details Defined in GI.Gio.Objects.Socket
IsInitable Subprocess Source # |
Instance details Defined in GI.Gio.Objects.Subprocess
IsInitable NetworkMonitor Source # |
Instance details Defined in GI.Gio.Interfaces.NetworkMonitor

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

## 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()` and`initableInit` 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