gio/auto/
initable.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{Cancellable, ffi};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// `GInitable` is implemented by objects that can fail during
10    /// initialization. If an object implements this interface then
11    /// it must be initialized as the first thing after construction,
12    /// either via [`InitableExt::init()`][crate::prelude::InitableExt::init()] or [`AsyncInitableExt::init_async()`][crate::prelude::AsyncInitableExt::init_async()]
13    /// (the latter is only available if it also implements [`AsyncInitable`][crate::AsyncInitable]).
14    ///
15    /// If the object is not initialized, or initialization returns with an
16    /// error, then all operations on the object except `g_object_ref()` and
17    /// `g_object_unref()` are considered to be invalid, and have undefined
18    /// behaviour. They will often fail with `critical()` or
19    /// `warning()`, but this must not be relied on.
20    ///
21    /// Users of objects implementing this are not intended to use
22    /// the interface method directly, instead it will be used automatically
23    /// in various ways. For C applications you generally just call
24    /// [`new()`][Self::new()] directly, or indirectly via a `foo_thing_new()` wrapper.
25    /// This will call [`InitableExt::init()`][crate::prelude::InitableExt::init()] under the cover, returning `NULL`
26    /// and setting a `GError` on failure (at which point the instance is
27    /// unreferenced).
28    ///
29    /// For bindings in languages where the native constructor supports
30    /// exceptions the binding could check for objects implementing `GInitable`
31    /// during normal construction and automatically initialize them, throwing
32    /// an exception on failure.
33    ///
34    /// # Implements
35    ///
36    /// [`InitableExt`][trait@crate::prelude::InitableExt]
37    #[doc(alias = "GInitable")]
38    pub struct Initable(Interface<ffi::GInitable, ffi::GInitableIface>);
39
40    match fn {
41        type_ => || ffi::g_initable_get_type(),
42    }
43}
44
45impl Initable {
46    pub const NONE: Option<&'static Initable> = None;
47}
48
49/// Trait containing all [`struct@Initable`] methods.
50///
51/// # Implementors
52///
53/// [`CharsetConverter`][struct@crate::CharsetConverter], [`DBusConnection`][struct@crate::DBusConnection], [`DBusObjectManagerClient`][struct@crate::DBusObjectManagerClient], [`DBusProxy`][struct@crate::DBusProxy], [`DBusServer`][struct@crate::DBusServer], [`DebugControllerDBus`][struct@crate::DebugControllerDBus], [`DebugController`][struct@crate::DebugController], [`InetAddressMask`][struct@crate::InetAddressMask], [`Initable`][struct@crate::Initable], [`MemoryMonitor`][struct@crate::MemoryMonitor], [`NetworkMonitor`][struct@crate::NetworkMonitor], [`PowerProfileMonitor`][struct@crate::PowerProfileMonitor], [`Socket`][struct@crate::Socket], [`Subprocess`][struct@crate::Subprocess]
54pub trait InitableExt: IsA<Initable> + 'static {
55    ///  implementation of init() can assume
56    /// (and assert) that it will only be called once. Previously, this documentation
57    /// recommended all #GInitable implementations should be idempotent; that
58    /// recommendation was relaxed in GLib 2.54.
59    ///
60    /// If a class explicitly supports being initialized multiple times, it is
61    /// recommended that the method is idempotent: multiple calls with the same
62    /// arguments should return the same results. Only the first call initializes
63    /// the object; further calls return the result of the first call.
64    ///
65    /// One reason why a class might need to support idempotent initialization is if
66    /// it is designed to be used via the singleton pattern, with a
67    /// #GObjectClass.constructor that sometimes returns an existing instance.
68    /// In this pattern, a caller would expect to be able to call g_initable_init()
69    /// on the result of g_object_new(), regardless of whether it is in fact a new
70    /// instance.
71    /// ## `cancellable`
72    /// optional #GCancellable object, [`None`] to ignore.
73    ///
74    /// # Returns
75    ///
76    /// [`true`] if successful. If an error has occurred, this function will
77    ///     return [`false`] and set @error appropriately if present.
78    #[doc(alias = "g_initable_init")]
79    unsafe fn init(&self, cancellable: Option<&impl IsA<Cancellable>>) -> Result<(), glib::Error> {
80        unsafe {
81            let mut error = std::ptr::null_mut();
82            let is_ok = ffi::g_initable_init(
83                self.as_ref().to_glib_none().0,
84                cancellable.map(|p| p.as_ref()).to_glib_none().0,
85                &mut error,
86            );
87            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
88            if error.is_null() {
89                Ok(())
90            } else {
91                Err(from_glib_full(error))
92            }
93        }
94    }
95}
96
97impl<O: IsA<Initable>> InitableExt for O {}
gio/auto/initable.rs

gio/auto/
initable.rs
