LCOV - code coverage report
Current view: top level - glib/gio - ginitable.c (source / functions) Hit Total Coverage
Test: unnamed Lines: 19 26 73.1 %
Date: 2024-03-26 05:16:46 Functions: 5 6 83.3 %
Branches: 7 10 70.0 %

           Branch data     Line data    Source code
       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   [ +  +  +  -  :      23622 : G_DEFINE_INTERFACE (GInitable, g_initable, G_TYPE_OBJECT)
                   +  + ]
      61                 :            : 
      62                 :            : static void
      63                 :        145 : g_initable_default_init (GInitableInterface *iface)
      64                 :            : {
      65                 :        145 : }
      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 [introduction][ginitable] 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                 :       5058 : g_initable_init (GInitable     *initable,
     120                 :            :                  GCancellable  *cancellable,
     121                 :            :                  GError       **error)
     122                 :            : {
     123                 :            :   GInitableIface *iface;
     124                 :            : 
     125                 :       5058 :   g_return_val_if_fail (G_IS_INITABLE (initable), FALSE);
     126                 :            : 
     127                 :       5058 :   iface = G_INITABLE_GET_IFACE (initable);
     128                 :            : 
     129                 :       5058 :   return (* iface->init) (initable, cancellable, error);
     130                 :            : }
     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                 :       2875 : g_initable_new (GType          object_type,
     154                 :            :                 GCancellable  *cancellable,
     155                 :            :                 GError       **error,
     156                 :            :                 const gchar   *first_property_name,
     157                 :            :                 ...)
     158                 :            : {
     159                 :            :   GObject *object;
     160                 :            :   va_list var_args;
     161                 :            : 
     162                 :       2875 :   va_start (var_args, first_property_name);
     163                 :       2875 :   object = g_initable_new_valist (object_type,
     164                 :            :                                   first_property_name, var_args,
     165                 :            :                                   cancellable, error);
     166                 :       2875 :   va_end (var_args);
     167                 :            : 
     168                 :       2875 :   return object;
     169                 :            : }
     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                 :          0 : g_initable_newv (GType          object_type,
     194                 :            :                  guint          n_parameters,
     195                 :            :                  GParameter    *parameters,
     196                 :            :                  GCancellable  *cancellable,
     197                 :            :                  GError       **error)
     198                 :            : {
     199                 :            :   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                 :            :     {
     207                 :          0 :       g_object_unref (obj);
     208                 :          0 :       return NULL;
     209                 :            :     }
     210                 :            : 
     211                 :          0 :   return (gpointer)obj;
     212                 :            : }
     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                 :       2875 : 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                 :            : {
     241                 :            :   GObject *obj;
     242                 :            : 
     243                 :       2875 :   g_return_val_if_fail (G_TYPE_IS_INITABLE (object_type), NULL);
     244                 :            : 
     245                 :       2875 :   obj = g_object_new_valist (object_type,
     246                 :            :                              first_property_name,
     247                 :            :                              var_args);
     248                 :            : 
     249         [ +  + ]:       2875 :   if (!g_initable_init (G_INITABLE (obj), cancellable, error))
     250                 :            :     {
     251                 :         88 :       g_object_unref (obj);
     252                 :         88 :       return NULL;
     253                 :            :     }
     254                 :            : 
     255                 :       2787 :   return obj;
     256                 :            : }

Generated by: LCOV version 1.14