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