Massively reorganise the client-side

This commit represents a rather complete rethinking of DConfEngine.

  - the different kinds of sources are now properly abstracted.  This
    will make landing NFS support substantially easier.

  - there is now substantially more internal documentation

  - DConfEngineMessage is gone and replaced with ordinary function calls
    to be implemented by the D-Bus glue code

  - the GDBus glue has been factored out and is now shared between the
    client library and GSettings

  - the "outstanding" queue logic from the GSettings backend is now in
    the engine

  - all changes now go through a single API that accepts a (new)
    DConfChangeset object.  Currently this only supports the current
    operations (ie: setting and resetting).  In the future this object
    will also support the directory operations required by GSettingsList
    and will be the basis for the new approach to implementing the
    'delayed' GSettingsBackend (which will be the method by which those
    two concepts can co-exist).

The (internal) API of the engine changed substantially.  This caused the
following:

  - the libdconf client library has been rewritten in C.  Most of the
    complicated aspects of it (that made it more convenience to use
    Vala) are now gone.

  - during the rewrite of libdconf, the DConfClient API changed a bit to
    look more like a proper GObject.  It now makes GIO-style use of
    thread-default main contexts and uses GObject signals for
    notifications (instead of hand-rolled callbacks).

  - the GSettings backend has been substantially simplified (the
    "outstanding" logic is gone).  No externally-visible changes.

  - the dbus-1 backend has taken a copy of the old engine code for now
    until it can be ported to the new engine and sufficiently tested.
    No externally-visible changes.

  - the dconf commandline tool and dconf-editor required minor changes
    to adjust to the DConfClient API changes

There is a substantial amount of cleaning up and finishing of work to be
done.  There are many stubs remaining.  There are likely still a large
number of bugs.

1 files changed, 100 insertions, 87 deletions

diff --git a/engine/dconf-engine.h b/engine/dconf-engine.h
index 25de43d..19b7097 100644
--- a/engine/dconf-engine.h
+++ b/engine/dconf-engine.h
@@ -22,123 +22,136 @@
 #ifndef __dconf_engine_h__
 #define __dconf_engine_h__
 
-#include <glib.h>
+#include "dconf-changeset-list.h"
+
+#include <gio/gio.h>
 
 typedef struct _DConfEngine DConfEngine;
 
-/**
- * DConfEngineMessage:
- *
- * This structure represents a number of DBus method call messages that #DConfEngine would like to send.
- *
- * #DConfEngine itself is unaware of a particular DBus or main loop implementation.  As such, all requests are
- * synchronous and non-blocking, but most of them produce a #DConfEngineMessage describing messages that must be
- * sent in order for the operation to be completed.
- *
- * @bus_name, @object_path, @interface_name, @method_name specify the respective header fields of the method
- * call.  These are always equal for all of the calls contained within a single #DConfEngineMessage.
- *
- * @reply_type is the expected reply type of the method call.  This is also the same for all calls contained
- * within a single #DConfEngineMessage.
- *
- * @n_messages is the number of messages to send.
- *
- * @bus_types and @parameters are both arrays, of length @n_messages.  Each element of @bus_type is the bus type
- * to send each method call on and each of @parameters is the body of that call.  The reason that there may be
- * several messages is that a single dconf "watch" operation may need to send multiple DBus "AddMatch" calls
- * (and usually to multiple busses).
- *
- * Each element in @bus_types is either 'y' for system bus or 'e' for session bus.
- *
- * A #DConfEngineMessage is always stack-allocated by the caller.  It must be cleared using
- * dconf_engine_message_destroy() when done.  It may be copied using dconf_engine_message_copy().
- */
-typedef struct
+typedef struct _DConfEngineCallHandle DConfEngineCallHandle;
+
+typedef enum
 {
-  const gchar         *bus_name;
-  const gchar         *object_path;
-  const gchar         *interface_name;
-  const gchar         *method_name;
+  DCONF_ERROR_FAILED,
+  DCONF_ERROR_NOT_WRITABLE
+} DConfEngineError;
 
-  gint                 n_messages;
-  GVariant           **parameters;
-  const gchar         *bus_types;
+#define DCONF_ERROR (g_quark_from_static_string ("dconf error quark"))
 
-  const GVariantType  *reply_type;
-} DConfEngineMessage;
+/* These functions need to be implemented by the client library */
 
+/* Sends a D-Bus message.
+ *
+ * When the reply comes back, the client library should call
+ * dconf_engine_handle_dbus_reply with the given user_data.
+ *
+ * This is called with the engine lock held.  Re-entering the engine
+ * from this function will cause a deadlock.
+ */
 G_GNUC_INTERNAL
-void                    dconf_engine_message_copy                       (DConfEngineMessage      *orig,
-                                                                         DConfEngineMessage      *copy);
+gboolean                dconf_engine_dbus_call_async_func               (GBusType                 bus_type,
+                                                                         const gchar             *bus_name,
+                                                                         const gchar             *object_path,
+                                                                         const gchar             *interface_name,
+                                                                         const gchar             *method_name,
+                                                                         GVariant                *parameters,
+                                                                         DConfEngineCallHandle   *handle,
+                                                                         GError                 **error);
+
+/* Sends a D-Bus message, synchronously.
+ *
+ * The lock is never held when calling this function (for the sake of
+ * not blocking requests in other threads) but you should have no reason
+ * to re-enter, so don't.
+ */
 G_GNUC_INTERNAL
-void                    dconf_engine_message_destroy                    (DConfEngineMessage      *message);
+GVariant *              dconf_engine_dbus_call_sync_func                (GBusType                 bus_type,
+                                                                         const gchar             *bus_name,
+                                                                         const gchar             *object_path,
+                                                                         const gchar             *interface_name,
+                                                                         const gchar             *method_name,
+                                                                         GVariant                *parameters,
+                                                                         const GVariantType      *expected_type,
+                                                                         GError                 **error);
 
+/* Notifies that a change occured.
+ *
+ * The engine lock is never held when calling this function so it is
+ * safe to run user callbacks or emit signals from this function.
+ */
 G_GNUC_INTERNAL
-DConfEngine *           dconf_engine_new                                (const gchar             *profile);
+void                    dconf_engine_change_notify                      (DConfEngine             *engine,
+                                                                         const gchar             *prefix,
+                                                                         const gchar * const     *changes,
+                                                                         const gchar             *tag,
+                                                                         gpointer                 user_data);
+
+/* These functions are implemented by the engine */
 G_GNUC_INTERNAL
-DConfEngine *           dconf_engine_new_for_db                         (const gchar             *db_name);
+void                    dconf_engine_call_handle_reply                  (DConfEngineCallHandle   *handle,
+                                                                         GVariant                *parameters,
+                                                                         const GError            *error);
+
 G_GNUC_INTERNAL
-guint64                 dconf_engine_get_state                          (DConfEngine             *engine);
+void                    dconf_engine_handle_dbus_signal                 (GBusType                 bus_type,
+                                                                         const gchar             *bus_name,
+                                                                         const gchar             *object_path,
+                                                                         const gchar             *signal_name,
+                                                                         GVariant                *parameters);
+
+G_GNUC_INTERNAL
+DConfEngine *           dconf_engine_new                                (gpointer                 user_data);
 
 G_GNUC_INTERNAL
 void                    dconf_engine_free                               (DConfEngine             *engine);
 
+/* Read API: always handled immediately */
 G_GNUC_INTERNAL
-GVariant *              dconf_engine_read                               (DConfEngine             *engine,
-                                                                         const gchar             *key);
+guint64                 dconf_engine_get_state                          (DConfEngine             *engine);
+
 G_GNUC_INTERNAL
-GVariant *              dconf_engine_read_default                       (DConfEngine             *engine,
+gboolean                dconf_engine_is_writable                        (DConfEngine             *engine,
                                                                          const gchar             *key);
+
 G_GNUC_INTERNAL
-GVariant *              dconf_engine_read_no_default                    (DConfEngine             *engine,
+GVariant *              dconf_engine_read                               (DConfEngine             *engine,
+                                                                         DConfChangesetList      *read_through,
                                                                          const gchar             *key);
+
 G_GNUC_INTERNAL
 gchar **                dconf_engine_list                               (DConfEngine             *engine,
-                                                                         const gchar             *path,
+                                                                         const gchar             *dir,
                                                                          gint                    *length);
 
+/* "Fast" API: all calls return immediately and look like they succeeded (from a local viewpoint) */
 G_GNUC_INTERNAL
-void                    dconf_engine_get_service_info                   (DConfEngine             *engine,
-                                                                         const gchar            **bus_type,
-                                                                         const gchar            **destination,
-                                                                         const gchar            **object_path);
+void                    dconf_engine_watch_fast                         (DConfEngine             *engine,
+                                                                         const gchar             *path);
+
 G_GNUC_INTERNAL
-gboolean                dconf_engine_is_writable                        (DConfEngine             *engine,
-                                                                         const gchar             *name);
+void                    dconf_engine_unwatch_fast                       (DConfEngine             *engine,
+                                                                         const gchar             *path);
+
 G_GNUC_INTERNAL
-gboolean                dconf_engine_write                              (DConfEngine             *engine,
-                                                                         const gchar             *key,
-                                                                         GVariant                *value,
-                                                                         DConfEngineMessage      *message,
+gboolean                dconf_engine_change_fast                        (DConfEngine             *engine,
+                                                                         DConfChangeset          *changeset,
                                                                          GError                 **error);
+
+/* Synchronous API: all calls block until completed */
 G_GNUC_INTERNAL
-gboolean                dconf_engine_write_many                         (DConfEngine             *engine,
-                                                                         const gchar             *prefix,
-                                                                         const gchar * const     *keys,
-                                                                         GVariant               **values,
-                                                                         DConfEngineMessage      *message,
-                                                                         GError                 **error);
+void                    dconf_engine_watch_sync                         (DConfEngine             *engine,
+                                                                         const gchar             *path);
+
 G_GNUC_INTERNAL
-void                    dconf_engine_watch                              (DConfEngine             *engine,
-                                                                         const gchar             *name,
-                                                                         DConfEngineMessage      *message);
-G_GNUC_INTERNAL
-void                    dconf_engine_unwatch                            (DConfEngine             *engine,
-                                                                         const gchar             *name,
-                                                                         DConfEngineMessage      *message);
-G_GNUC_INTERNAL
-gboolean                dconf_engine_decode_notify                      (DConfEngine             *engine,
-                                                                         const gchar             *anti_expose,
-                                                                         const gchar            **prefix,
-                                                                         const gchar           ***keys,
-                                                                         guint                    bus_type,
-                                                                         const gchar             *sender,
-                                                                         const gchar             *interface,
-                                                                         const gchar             *member,
-                                                                         GVariant                *body);
-G_GNUC_INTERNAL
-gboolean                dconf_engine_decode_writability_notify          (const gchar            **path,
-                                                                         const gchar             *iface,
-                                                                         const gchar             *method,
-                                                                         GVariant                *body);
+void                    dconf_engine_unwatch_sync                       (DConfEngine             *engine,
+                                                                         const gchar             *path);
+
+G_GNUC_INTERNAL
+gboolean                dconf_engine_change_sync                        (DConfEngine             *engine,
+                                                                         DConfChangeset          *changeset,
+                                                                         gchar                  **tag,
+                                                                         GError                 **error);
+
+/* Asynchronous API: not implemented yet (and maybe never?) */
+
 #endif /* __dconf_engine_h__ */