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::{ffi, Cancellable};
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
49mod sealed {
50 pub trait Sealed {}
51 impl<T: super::IsA<super::Initable>> Sealed for T {}
52}
53
54/// Trait containing all [`struct@Initable`] methods.
55///
56/// # Implementors
57///
58/// [`CharsetConverter`][struct@crate::CharsetConverter], [`DBusConnection`][struct@crate::DBusConnection], [`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]
59pub trait InitableExt: IsA<Initable> + sealed::Sealed + 'static {
60 /// Initializes the object implementing the interface.
61 ///
62 /// This method is intended for language bindings. If writing in C,
63 /// g_initable_new() should typically be used instead.
64 ///
65 /// The object must be initialized before any real use after initial
66 /// construction, either with this function or g_async_initable_init_async().
67 ///
68 /// Implementations may also support cancellation. If @cancellable is not [`None`],
69 /// then initialization can be cancelled by triggering the cancellable object
70 /// from another thread. If the operation was cancelled, the error
71 /// [`IOErrorEnum::Cancelled`][crate::IOErrorEnum::Cancelled] will be returned. If @cancellable is not [`None`] and
72 /// the object doesn't support cancellable initialization the error
73 /// [`IOErrorEnum::NotSupported`][crate::IOErrorEnum::NotSupported] will be returned.
74 ///
75 /// If the object is not initialized, or initialization returns with an
76 /// error, then all operations on the object except g_object_ref() and
77 /// g_object_unref() are considered to be invalid, and have undefined
78 /// behaviour. See the [description][`Initable`][crate::Initable]#description] for more details.
79 ///
80 /// Callers should not assume that a class which implements #GInitable can be
81 /// initialized multiple times, unless the class explicitly documents itself as
82 /// supporting this. Generally, a class’ implementation of init() can assume
83 /// (and assert) that it will only be called once. Previously, this documentation
84 /// recommended all #GInitable implementations should be idempotent; that
85 /// recommendation was relaxed in GLib 2.54.
86 ///
87 /// If a class explicitly supports being initialized multiple times, it is
88 /// recommended that the method is idempotent: multiple calls with the same
89 /// arguments should return the same results. Only the first call initializes
90 /// the object; further calls return the result of the first call.
91 ///
92 /// One reason why a class might need to support idempotent initialization is if
93 /// it is designed to be used via the singleton pattern, with a
94 /// #GObjectClass.constructor that sometimes returns an existing instance.
95 /// In this pattern, a caller would expect to be able to call g_initable_init()
96 /// on the result of g_object_new(), regardless of whether it is in fact a new
97 /// instance.
98 /// ## `cancellable`
99 /// optional #GCancellable object, [`None`] to ignore.
100 ///
101 /// # Returns
102 ///
103 /// [`true`] if successful. If an error has occurred, this function will
104 /// return [`false`] and set @error appropriately if present.
105 #[doc(alias = "g_initable_init")]
106 unsafe fn init(&self, cancellable: Option<&impl IsA<Cancellable>>) -> Result<(), glib::Error> {
107 let mut error = std::ptr::null_mut();
108 let is_ok = ffi::g_initable_init(
109 self.as_ref().to_glib_none().0,
110 cancellable.map(|p| p.as_ref()).to_glib_none().0,
111 &mut error,
112 );
113 debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
114 if error.is_null() {
115 Ok(())
116 } else {
117 Err(from_glib_full(error))
118 }
119 }
120}
121
122impl<O: IsA<Initable>> InitableExt for O {}