[gnio] Add GInitable interface

[Alexander Larsson <alexl src gnome org>]

commit 103093e9bf73a1504156394767f112410f642d6c
Author: Alexander Larsson <alexl redhat com>
Date:   Wed May 6 22:15:33 2009 +0200

    Add GInitable interface
    
    Add GInitable interface, to be used for object construction that
    may fail. Will be needed by GSocket, but is generally useful.
---
 gio/Makefile.am |    2 +
 gio/ginitable.c |  198 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 gio/ginitable.h |   94 ++++++++++++++++++++++++++
 3 files changed, 294 insertions(+), 0 deletions(-)

diff --git a/gio/Makefile.am b/gio/Makefile.am
index d4fa639..a39f9f8 100644
--- a/gio/Makefile.am
+++ b/gio/Makefile.am
@@ -13,6 +13,7 @@ sources = \
 	gnio-marshal.c			\
 	gnio-marshal.h			\
 	gnioenums.c			\
+	ginitable.c			\
 	gsocket.c			\
 	gsocketclient.c			\
 	gsocketconnection.c		\
@@ -50,6 +51,7 @@ headers = \
 	giostream.h			\
 	gnio.h				\
 	gnioerror.h			\
+	ginitable.h			\
 	gsocket.h			\
 	gsocketclient.h			\
 	gsocketconnection.h		\
diff --git a/gio/ginitable.c b/gio/ginitable.c
new file mode 100644
index 0000000..36ee963
--- /dev/null
+++ b/gio/ginitable.c
@@ -0,0 +1,198 @@
+/* GIO - GLib Input, Output and Streaming Library
+ *
+ * Copyright (C) 2009 Red Hat, Inc.
+ *
+ * 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 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, write to the
+ * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Alexander Larsson <alexl redhat com>
+ */
+
+#include "config.h"
+#include "ginitable.h"
+
+/**
+ * SECTION:ginitable
+ * @short_description: Failable object initialization interface
+ * @include: gio/gio.h
+ * @see_also: #GAsyncInitable
+ *
+ * #GInitable is implemented by objects that can fail during
+ * initialization. If an object implements this interface the
+ * g_initable_init() function must be called as the first thing
+ * after construction. If g_initable_init() is not called, or if
+ * it returns an error, all further operations on the object
+ * should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error.
+ *
+ * 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
+ * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
+ * This will call g_initable_init() under the cover, returning %NULL and
+ * setting a %GError on failure.
+ *
+ * For bindings in languages where the native constructor supports
+ * exceptions the binding could check for objects implemention %GInitable
+ * during normal construction and automatically initialize them, throwing
+ * an exception on failure.
+ **/
+
+static void g_initable_base_init (gpointer g_class);
+
+GType
+g_initable_get_type (void)
+{
+  static volatile gsize g_define_type_id__volatile = 0;
+
+  if (g_once_init_enter (&g_define_type_id__volatile))
+    {
+      const GTypeInfo initable_info =
+      {
+        sizeof (GInitableIface), /* class_size */
+	g_initable_base_init,   /* base_init */
+	NULL,		/* base_finalize */
+	NULL,
+	NULL,		/* class_finalize */
+	NULL,		/* class_data */
+	0,
+	0,              /* n_preallocs */
+	NULL
+      };
+      GType g_define_type_id =
+	g_type_register_static (G_TYPE_INTERFACE, I_("GInitable"),
+				&initable_info, 0);
+
+      g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_OBJECT);
+
+      g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
+    }
+
+  return g_define_type_id__volatile;
+}
+
+static void
+g_initable_base_init (gpointer g_class)
+{
+}
+
+/**
+ * g_initable_init:
+ * @initable: a #GInitable.
+ * @cancellable: optional #GCancellable object, %NULL to ignore. 
+ * @error: a #GError location to store the error occuring, or %NULL to 
+ * ignore.
+ *
+ * Initializes the object implementing the interface. This must be
+ * done before any real use of the object after initial construction.
+ *
+ * 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 this function is not called, or returns with an error then all
+ * operations on the object should fail, generally returning the
+ * error %G_IO_ERROR_NOT_INITIALIZED.
+ *
+ * Implementations of this method must be idempotent, i.e. multiple calls
+ * to this function should return the same results. Only the first call
+ * initializes the object, further calls return the result of the first
+ * call. This is so that its safe to implement the singleton pattern in
+ * the GObject constructor function.
+ *
+ * Returns: %TRUE if successful. If an error
+ *     has occurred, this function will return %FALSE and set @error
+ *     appropriately if present.
+ **/
+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);
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
diff --git a/gio/ginitable.h b/gio/ginitable.h
new file mode 100644
index 0000000..134262f
--- /dev/null
+++ b/gio/ginitable.h
@@ -0,0 +1,94 @@
+/* GIO - GLib Input, Output and Streaming Library
+ *
+ * Copyright (C) 2009 Red Hat, Inc.
+ *
+ * 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 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, write to the
+ * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Alexander Larsson <alexl redhat com>
+ */
+
+#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
+#error "Only <gio/gio.h> can be included directly."
+#endif
+
+#ifndef __G_INITABLE_H__
+#define __G_INITABLE_H__
+
+#include <gio/giotypes.h>
+
+G_BEGIN_DECLS
+
+#define G_TYPE_INITABLE            (g_initable_get_type ())
+#define G_INITABLE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_INITABLE, GInitable))
+#define G_IS_INITABLE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_INITABLE))
+#define G_INITABLE_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_INITABLE, GInitableIface))
+#define G_TYPE_IS_INITABLE(type)   (g_type_is_a ((type), G_TYPE_INITABLE))
+
+/**
+ * GInitable:
+ *
+ * Init object for streaming operations.
+ **/
+typedef struct _GInitableIface GInitableIface;
+typedef struct _GInitable      GInitable;
+
+/**
+ * GInitableIface:
+ * @g_iface: The parent interface.
+ * @init: Initializes the object.
+ *
+ * Provides an interface for initializing object such that initialization may fail.
+ **/
+struct _GInitableIface
+{
+  GTypeInterface g_iface;
+
+  /* Virtual Table */
+
+  gboolean    (* init) (GInitable    *initable,
+			GCancellable *cancellable,
+			GError      **error);
+};
+
+/* TODO: Move to gioenums.h */
+#define G_IO_ERROR_NOT_INITIALIZED 1000
+
+GType    g_initable_get_type   (void) G_GNUC_CONST;
+
+gboolean g_initable_init       (GInitable     *initable,
+				GCancellable  *cancellable,
+				GError       **error);
+
+gpointer g_initable_new        (GType          object_type,
+				GCancellable  *cancellable,
+				GError       **error,
+				const gchar   *first_property_name,
+				...);
+gpointer g_initable_newv       (GType          object_type,
+				guint          n_parameters,
+				GParameter    *parameters,
+				GCancellable  *cancellable,
+				GError       **error);
+GObject* g_initable_new_valist (GType          object_type,
+				const gchar   *first_property_name,
+				va_list        var_args,
+				GCancellable  *cancellable,
+				GError       **error);
+
+G_END_DECLS
+
+
+#endif /* __G_INITABLE_H__ */