/src/glib/gio/ginitable.c

Source (jump to first uncovered line)
/* GIO - GLib Input, Output and Streaming Library
 *
 * Copyright (C) 2009 Red Hat, Inc.
 *
 * SPDX-License-Identifier: LGPL-2.1-or-later
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
 *
 * Author: Alexander Larsson <alexl@redhat.com>
 */

#include "config.h"
#include "ginitable.h"
#include "glibintl.h"


/**
 * GInitable:
 *
 * `GInitable` 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 [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async]
 * (the latter is only available if it also implements [iface@Gio.AsyncInitable]).
 *
 * If the object is not initialized, or initialization returns with an
 * error, then all operations on the object except `g_object_ref()` and
 * `g_object_unref()` are considered to be invalid, and have undefined
 * behaviour. They will often fail with [func@GLib.critical] or
 * [func@GLib.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
 * [func@Gio.Initable.new] directly, or indirectly via a `foo_thing_new()` wrapper.
 * This will call [method@Gio.Initable.init] under the cover, returning `NULL`
 * 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
 */

typedef GInitableIface GInitableInterface;
G_DEFINE_INTERFACE (GInitable, g_initable, G_TYPE_OBJECT)

static void
g_initable_default_init (GInitableInterface *iface)
{
}

/**
 * g_initable_init:
 * @initable: a #GInitable.
 * @cancellable: optional #GCancellable object, %NULL to ignore.
 * @error: a #GError location to store the error occurring, or %NULL to
 * ignore.
 *
 * 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 g_async_initable_init_async().
 *
 * Implementations may also support cancellation. If @cancellable is not %NULL,
 * then initialization can be cancelled by triggering the cancellable object
 * from another thread. If the operation was cancelled, the error
 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
 * the object doesn't support cancellable initialization the error
 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
 *
 * If the object is not initialized, or initialization returns with an
 * error, then all operations on the object except g_object_ref() and
 * g_object_unref() are considered to be invalid, and have undefined
 * behaviour. See the [description][iface@Gio.Initable#description] for more details.
 *
 * Callers should not assume that a class which implements #GInitable 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 #GInitable 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
 * #GObjectClass.constructor that sometimes returns an existing instance.
 * In this pattern, a caller would expect to be able to call g_initable_init()
 * on the result of g_object_new(), regardless of whether it is in fact a new
 * instance.
 *
 * Returns: %TRUE if successful. If an error has occurred, this function will
 *     return %FALSE and set @error appropriately if present.
 *
 * Since: 2.22
 */
gboolean
g_initable_init (GInitable     *initable,
     GCancellable  *cancellable,
     GError       **error)
{
  GInitableIface *iface;

  g_return_val_if_fail (G_IS_INITABLE (initable), FALSE);

  iface = G_INITABLE_GET_IFACE (initable);

  return (* iface->init) (initable, cancellable, error);
}

/**
 * g_initable_new:
 * @object_type: a #GType supporting #GInitable.
 * @cancellable: optional #GCancellable object, %NULL to ignore.
 * @error: a #GError location to store the error occurring, or %NULL to
 *    ignore.
 * @first_property_name: (nullable): the name of the first property, or %NULL if no
 *     properties
 * @...:  the value if the first property, followed by and other property
 *    value pairs, and ended by %NULL.
 *
 * Helper function for constructing #GInitable object. This is
 * similar to g_object_new() but also initializes the object
 * and returns %NULL, setting an error on failure.
 *
 * Returns: (type GObject.Object) (transfer full): a newly allocated
 *      #GObject, or %NULL on error
 *
 * Since: 2.22
 */
gpointer
g_initable_new (GType          object_type,
    GCancellable  *cancellable,
    GError       **error,
    const gchar   *first_property_name,
    ...)
{
  GObject *object;
  va_list var_args;

  va_start (var_args, first_property_name);
  object = g_initable_new_valist (object_type,
          first_property_name, var_args,
          cancellable, error);
  va_end (var_args);

  return object;
}

/**
 * g_initable_newv:
 * @object_type: a #GType supporting #GInitable.
 * @n_parameters: the number of parameters in @parameters
 * @parameters: (array length=n_parameters): the parameters to use to construct the object
 * @cancellable: optional #GCancellable object, %NULL to ignore.
 * @error: a #GError location to store the error occurring, or %NULL to
 *     ignore.
 *
 * Helper function for constructing #GInitable object. This is
 * similar to g_object_newv() but also initializes the object
 * and returns %NULL, setting an error on failure.
 *
 * Returns: (type GObject.Object) (transfer full): a newly allocated
 *      #GObject, or %NULL on error
 *
 * Since: 2.22
 * Deprecated: 2.54: Use g_object_new_with_properties() and
 * g_initable_init() instead. See #GParameter for more information.
 */
G_GNUC_BEGIN_IGNORE_DEPRECATIONS
gpointer
g_initable_newv (GType          object_type,
     guint          n_parameters,
     GParameter    *parameters,
     GCancellable  *cancellable,
     GError       **error)
{
  GObject *obj;

  g_return_val_if_fail (G_TYPE_IS_INITABLE (object_type), NULL);

  obj = g_object_newv (object_type, n_parameters, parameters);

  if (!g_initable_init (G_INITABLE (obj), cancellable, error))
    {
      g_object_unref (obj);
      return NULL;
    }

  return (gpointer)obj;
}
G_GNUC_END_IGNORE_DEPRECATIONS

/**
 * g_initable_new_valist:
 * @object_type: a #GType supporting #GInitable.
 * @first_property_name: the name of the first property, followed by
 * the value, and other property value pairs, and ended by %NULL.
 * @var_args: The var args list generated from @first_property_name.
 * @cancellable: optional #GCancellable object, %NULL to ignore.
 * @error: a #GError location to store the error occurring, or %NULL to
 *     ignore.
 *
 * Helper function for constructing #GInitable object. This is
 * similar to g_object_new_valist() but also initializes the object
 * and returns %NULL, setting an error on failure.
 *
 * Returns: (type GObject.Object) (transfer full): a newly allocated
 *      #GObject, or %NULL on error
 *
 * Since: 2.22
 */
GObject*
g_initable_new_valist (GType          object_type,
           const gchar   *first_property_name,
           va_list        var_args,
           GCancellable  *cancellable,
           GError       **error)
{
  GObject *obj;

  g_return_val_if_fail (G_TYPE_IS_INITABLE (object_type), NULL);

  obj = g_object_new_valist (object_type,
           first_property_name,
           var_args);

  if (!g_initable_init (G_INITABLE (obj), cancellable, error))
    {
      g_object_unref (obj);
      return NULL;
    }

  return obj;
}

Coverage Report

Created: 2025-06-13 06:21

Line	Count	Source (jump to first uncovered line)
1		/* GIO - GLib Input, Output and Streaming Library
2		*
3		* Copyright (C) 2009 Red Hat, Inc.
4		*
5		* SPDX-License-Identifier: LGPL-2.1-or-later
6		*
7		* This library is free software; you can redistribute it and/or
8		* modify it under the terms of the GNU Lesser General Public
9		* License as published by the Free Software Foundation; either
10		* version 2.1 of the License, or (at your option) any later version.
11		*
12		* This library is distributed in the hope that it will be useful,
13		* but WITHOUT ANY WARRANTY; without even the implied warranty of
14		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15		* Lesser General Public License for more details.
16		*
17		* You should have received a copy of the GNU Lesser General
18		* Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19		*
20		* Author: Alexander Larsson <alexl@redhat.com>
21		*/
22
23		#include "config.h"
24		#include "ginitable.h"
25		#include "glibintl.h"
26
27
28		/**
29		* GInitable:
30		*
31		* `GInitable` is implemented by objects that can fail during
32		* initialization. If an object implements this interface then
33		* it must be initialized as the first thing after construction,
34		* either via [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async]
35		* (the latter is only available if it also implements [iface@Gio.AsyncInitable]).
36		*
37		* If the object is not initialized, or initialization returns with an
38		* error, then all operations on the object except `g_object_ref()` and
39		* `g_object_unref()` are considered to be invalid, and have undefined
40		* behaviour. They will often fail with [func@GLib.critical] or
41		* [func@GLib.warning], but this must not be relied on.
42		*
43		* Users of objects implementing this are not intended to use
44		* the interface method directly, instead it will be used automatically
45		* in various ways. For C applications you generally just call
46		* [func@Gio.Initable.new] directly, or indirectly via a `foo_thing_new()` wrapper.
47		* This will call [method@Gio.Initable.init] under the cover, returning `NULL`
48		* and setting a `GError` on failure (at which point the instance is
49		* unreferenced).
50		*
51		* For bindings in languages where the native constructor supports
52		* exceptions the binding could check for objects implementing `GInitable`
53		* during normal construction and automatically initialize them, throwing
54		* an exception on failure.
55		*
56		* Since: 2.22
57		*/
58
59		typedef GInitableIface GInitableInterface;
60		G_DEFINE_INTERFACE (GInitable, g_initable, G_TYPE_OBJECT)
61
62		static void
63		g_initable_default_init (GInitableInterface *iface)
64	1	{
65	1	}
66
67		/**
68		* g_initable_init:
69		* @initable: a #GInitable.
70		* @cancellable: optional #GCancellable object, %NULL to ignore.
71		* @error: a #GError location to store the error occurring, or %NULL to
72		* ignore.
73		*
74		* Initializes the object implementing the interface.
75		*
76		* This method is intended for language bindings. If writing in C,
77		* g_initable_new() should typically be used instead.
78		*
79		* The object must be initialized before any real use after initial
80		* construction, either with this function or g_async_initable_init_async().
81		*
82		* Implementations may also support cancellation. If @cancellable is not %NULL,
83		* then initialization can be cancelled by triggering the cancellable object
84		* from another thread. If the operation was cancelled, the error
85		* %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
86		* the object doesn't support cancellable initialization the error
87		* %G_IO_ERROR_NOT_SUPPORTED will be returned.
88		*
89		* If the object is not initialized, or initialization returns with an
90		* error, then all operations on the object except g_object_ref() and
91		* g_object_unref() are considered to be invalid, and have undefined
92		* behaviour. See the [description][iface@Gio.Initable#description] for more details.
93		*
94		* Callers should not assume that a class which implements #GInitable can be
95		* initialized multiple times, unless the class explicitly documents itself as
96		* supporting this. Generally, a class’ implementation of init() can assume
97		* (and assert) that it will only be called once. Previously, this documentation
98		* recommended all #GInitable implementations should be idempotent; that
99		* recommendation was relaxed in GLib 2.54.
100		*
101		* If a class explicitly supports being initialized multiple times, it is
102		* recommended that the method is idempotent: multiple calls with the same
103		* arguments should return the same results. Only the first call initializes
104		* the object; further calls return the result of the first call.
105		*
106		* One reason why a class might need to support idempotent initialization is if
107		* it is designed to be used via the singleton pattern, with a
108		* #GObjectClass.constructor that sometimes returns an existing instance.
109		* In this pattern, a caller would expect to be able to call g_initable_init()
110		* on the result of g_object_new(), regardless of whether it is in fact a new
111		* instance.
112		*
113		* Returns: %TRUE if successful. If an error has occurred, this function will
114		* return %FALSE and set @error appropriately if present.
115		*
116		* Since: 2.22
117		*/
118		gboolean
119		g_initable_init (GInitable *initable,
120		GCancellable *cancellable,
121		GError **error)
122	140	{
123	140	GInitableIface *iface;
124
125	140	g_return_val_if_fail (G_IS_INITABLE (initable), FALSE);
126
127	140	iface = G_INITABLE_GET_IFACE (initable);
128
129	140	return (* iface->init) (initable, cancellable, error);
130	140	}
131
132		/**
133		* g_initable_new:
134		* @object_type: a #GType supporting #GInitable.
135		* @cancellable: optional #GCancellable object, %NULL to ignore.
136		* @error: a #GError location to store the error occurring, or %NULL to
137		* ignore.
138		* @first_property_name: (nullable): the name of the first property, or %NULL if no
139		* properties
140		* @...: the value if the first property, followed by and other property
141		* value pairs, and ended by %NULL.
142		*
143		* Helper function for constructing #GInitable object. This is
144		* similar to g_object_new() but also initializes the object
145		* and returns %NULL, setting an error on failure.
146		*
147		* Returns: (type GObject.Object) (transfer full): a newly allocated
148		* #GObject, or %NULL on error
149		*
150		* Since: 2.22
151		*/
152		gpointer
153		g_initable_new (GType object_type,
154		GCancellable *cancellable,
155		GError **error,
156		const gchar *first_property_name,
157		...)
158	140	{
159	140	GObject *object;
160	140	va_list var_args;
161
162	140	va_start (var_args, first_property_name);
163	140	object = g_initable_new_valist (object_type,
164	140	first_property_name, var_args,
165	140	cancellable, error);
166	140	va_end (var_args);
167
168	140	return object;
169	140	}
170
171		/**
172		* g_initable_newv:
173		* @object_type: a #GType supporting #GInitable.
174		* @n_parameters: the number of parameters in @parameters
175		* @parameters: (array length=n_parameters): the parameters to use to construct the object
176		* @cancellable: optional #GCancellable object, %NULL to ignore.
177		* @error: a #GError location to store the error occurring, or %NULL to
178		* ignore.
179		*
180		* Helper function for constructing #GInitable object. This is
181		* similar to g_object_newv() but also initializes the object
182		* and returns %NULL, setting an error on failure.
183		*
184		* Returns: (type GObject.Object) (transfer full): a newly allocated
185		* #GObject, or %NULL on error
186		*
187		* Since: 2.22
188		* Deprecated: 2.54: Use g_object_new_with_properties() and
189		* g_initable_init() instead. See #GParameter for more information.
190		*/
191		G_GNUC_BEGIN_IGNORE_DEPRECATIONS
192		gpointer
193		g_initable_newv (GType object_type,
194		guint n_parameters,
195		GParameter *parameters,
196		GCancellable *cancellable,
197		GError **error)
198	0	{
199	0	GObject *obj;
200
201	0	g_return_val_if_fail (G_TYPE_IS_INITABLE (object_type), NULL);
202
203	0	obj = g_object_newv (object_type, n_parameters, parameters);
204
205	0	if (!g_initable_init (G_INITABLE (obj), cancellable, error))
206	0	{
207	0	g_object_unref (obj);
208	0	return NULL;
209	0	}
210
211	0	return (gpointer)obj;
212	0	}
213		G_GNUC_END_IGNORE_DEPRECATIONS
214
215		/**
216		* g_initable_new_valist:
217		* @object_type: a #GType supporting #GInitable.
218		* @first_property_name: the name of the first property, followed by
219		* the value, and other property value pairs, and ended by %NULL.
220		* @var_args: The var args list generated from @first_property_name.
221		* @cancellable: optional #GCancellable object, %NULL to ignore.
222		* @error: a #GError location to store the error occurring, or %NULL to
223		* ignore.
224		*
225		* Helper function for constructing #GInitable object. This is
226		* similar to g_object_new_valist() but also initializes the object
227		* and returns %NULL, setting an error on failure.
228		*
229		* Returns: (type GObject.Object) (transfer full): a newly allocated
230		* #GObject, or %NULL on error
231		*
232		* Since: 2.22
233		*/
234		GObject*
235		g_initable_new_valist (GType object_type,
236		const gchar *first_property_name,
237		va_list var_args,
238		GCancellable *cancellable,
239		GError **error)
240	140	{
241	140	GObject *obj;
242
243	140	g_return_val_if_fail (G_TYPE_IS_INITABLE (object_type), NULL);
244
245	140	obj = g_object_new_valist (object_type,
246	140	first_property_name,
247	140	var_args);
248
249	140	if (!g_initable_init (G_INITABLE (obj), cancellable, error))
250	28	{
251	28	g_object_unref (obj);
252	28	return NULL;
253	28	}
254
255	112	return obj;
256	140	}