Merge lp:geis/2.x into lp:geis

[Stephen M. Webb]

This change is some basic infrastructure required for configurable back ends (eg. DBus client, local grail, maverick-style XCB).

[Henrik Rydberg (rydberg)]

Looks ok. Things are getting closer. :-)

[Henrik Rydberg (rydberg)]

> Looks ok. Things are getting closer. :-)

review: Approve

[Chase Douglas (chasedouglas)]

Do we want to be able to specify a timeout value for geis_backend_multiplexor_pump?

Otherwise, looks good to me.

[Mohamed IKBEL Boulabiar (boulabiar)]

Looks Good !

("teh", "isn;t" in the comments detected :P)

review: Approve

=== modified file 'ChangeLog'
--- ChangeLog	2010-11-29 14:32:34 +0000
+++ ChangeLog	2010-12-02 19:24:57 +0000
@@ -1,3 +1,52 @@
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Added a back end base and test fixture.
+
+  * libutouch-geis/geis_backend.c: new file
+  * libutouch-geis/geis_backend.h: new file
+  * libutouch-geis/geis_backend_protected.h: new file
+  * libutouch-geis/geis_backend_test_fixture.c: new file
+  * libutouch-geis/geis_backend_test_fixture.h: new file
+  * include/geis/geis.h (GEIS_INIT_SERVICE_PROVIDER): changed constant value
+    (GEIS_INIT_UTOUCH_MOCK_ENGINE): added new constant
+  * libutouch-geis/Makefile.am: added new files
+  * libutouch-geis/geis.c (struct _Geis): replaced is_test_fixture with backend
+    (geis_set_valist): created new test fixture backend
+    (geis_delete): destroyed backend
+  * testsuite/geis2/check_config.c: used new name for test fixture back end
+  * testsuite/geis2/check_geis_new.c: same
+  * testsuite/geis2/check_subscription.c: idem
+  * testsuite/libutouch-geis/check_subscription.c: ditto
+
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Added a back end multiplexor.
+
+  * libutouch-geis/geis_backend_multiplexor.c: new file
+  * libutouch-geis/geis_backend_multiplexor.h: new file
+  * testsuite/libutouch-geis/check_backend_multiplexor.c: new testsuite
+  * include/geis/geis.h (GeisStatus): added new status codes
+    GEIS_STATUS_CONTINUE and GEIS_STATUS_EMPTY
+    (GEIS_CONFIG_UTOUCH_MAX_EVENTS): new configuration item
+  * libutouch-geis/Makefile.am: added new files
+  * libutouch-geis/geis.c (struct _Geis): added backend_multiplexor field
+    (geis_new_empty): initialized it
+    (geis_delete): destroyed it
+    (geis_get_configuration): retrieved its file descriptor and config value
+    (geis_set_configuration): set its configuration value
+  * testsuite/geis2/check_error_codes.c: checked new status codes
+  * testsuite/libutouch-geis/Makefile.am
+  * testsuite/libutouch-geis/check_geis2_internals.c
+
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Refactored geis_private.h to provide improved data encapsulation.
+
+  * libutouch-geis/geis_private.h (struct _Geis): moved to geis.c
+    (geis_error_stack): new function
+  * libutouch-geis/geis.c: implemented new function
+  * libutouch-geis/geis_error.c: used new function
+
 2010-11-29  Stephen M. Webb  <[e-mail]>
 
   Fixed a typo in the Doxygen comments in geis.h.
 
=== modified file 'doc/Doxyfile'
--- doc/Doxyfile	2010-08-06 21:16:55 +0000
+++ doc/Doxyfile	2010-12-02 19:24:57 +0000
@@ -590,7 +590,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../geis
+INPUT                  = ../include/geis
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
 
=== modified file 'include/geis/geis.h'
--- include/geis/geis.h	2010-11-29 14:32:34 +0000
+++ include/geis/geis.h	2010-12-02 19:24:57 +0000
@@ -120,6 +120,10 @@
 typedef enum GeisStatus
 {
   GEIS_STATUS_SUCCESS       = 0,    /**< normal successful completion */
+  GEIS_STATUS_CONTINUE      = 20,   /**< normal successful completion
+                                         with data still remaining */
+  GEIS_STATUS_EMPTY         = 21,   /**< normal successful completion
+                                         with no data retrieved */
   GEIS_STATUS_NOT_SUPPORTED = 10,   /**< a requested feature is not supported */
   GEIS_BAD_ARGUMENT         = 1000, /**< a bad argument value was passed */
   GEIS_UNKNOWN_ERROR        = 9999, /**< any other error condition */
@@ -190,12 +194,40 @@
 /* @} */
 
 /**
- * @defgroup geis_2_geis The Geis API Object
- *
- * @{
- */
-
-#define GEIS_INIT_SERVICE_PROVIDER  "geis-init-server"
+ * @defgroup geis_2_geis The Geis API Object (GEIS v2.0)
+ *
+ * @{
+ */
+
+/**
+ * @defgroup geis_2_geis_init_args Specified Initialization Arguments
+ *
+ * These initialization arguments are defined by the GEIS specification.
+ *
+ * @{
+ */
+
+/**
+ * Enables GEIS to provide a networked service.
+ *
+ * This initialization argument takes no parameters.
+ */
+#define GEIS_INIT_SERVICE_PROVIDER   "org.libgeis.init.server"
+
+/* @} */
+
+/**
+ * @defgroup geis_2_geis_init_vendor Vendor-defined Initialization Arguments
+ *
+ * These initialization arguments are not a part of te GEIS specification and
+ * may change.
+ *
+ * @{
+ */
+
+#define GEIS_INIT_UTOUCH_MOCK_ENGINE "com.canonical.utouch.mock.engine"
+
+/* @} */
 
 
 typedef struct _Geis *Geis;
@@ -332,8 +364,31 @@
  * @{
  */
 
+/**
+ * @defgroup geis2_config_spec Required Configuration Items
+ *
+ * These configuration items are defined by the GEIS specification.
+ *
+ * @{
+ */
+
 #define GEIS_CONFIGURATION_FD "org.libgeis.configuration.fd"
 
+/* @} */
+
+/**
+ * @defgroup geis2_config_vendor Vendor-defined Configuration Items
+ *
+ * These configuration items are not a part of the GEIS specification and may
+ * change.
+ *
+ * @{
+ */
+
+#define GEIS_CONFIG_UTOUCH_MAX_EVENTS  "com.canonical.utouch.max_events"
+
+/* @} */
+
 /**
  * Gets a feature configuration value.
  *
 
=== modified file 'libutouch-geis/Makefile.am'
--- libutouch-geis/Makefile.am	2010-11-29 02:16:02 +0000
+++ libutouch-geis/Makefile.am	2010-12-02 19:24:57 +0000
@@ -23,11 +23,15 @@
 lib_LTLIBRARIES = libutouch-geis.la
 
 libutouch_geis_la_SOURCES = \
-	geis_attr.h         geis_attr.c \
-	geis_error.h        geis_error.c \
-	geis_logging.h      geis_logging.c \
-	geis_subscription.h geis_subscription.c \
-	geis_private.h      geis.c
+	geis_attr.h                 geis_attr.c \
+	geis_backend.h              geis_backend.c \
+	geis_backend_protected.h \
+	geis_backend_test_fixture.h geis_backend_test_fixture.c \
+	geis_backend_multiplexor.h  geis_backend_multiplexor.c \
+	geis_error.h                geis_error.c \
+	geis_logging.h              geis_logging.c \
+	geis_subscription.h         geis_subscription.c \
+	geis_private.h              geis.c
 
 libutouch_geis_la_CPPFLAGS = \
 	-Wall -Wextra \
 
=== modified file 'libutouch-geis/geis.c'
--- libutouch-geis/geis.c	2010-11-29 02:16:02 +0000
+++ libutouch-geis/geis.c	2010-12-02 19:24:57 +0000
@@ -21,12 +21,23 @@
 #include "geis_config.h"
 #include "geis_private.h"
 
+#include "geis_backend.h"
+#include "geis_backend_test_fixture.h"
+#include "geis_backend_multiplexor.h"
 #include "geis_error.h"
 #include "geis_logging.h"
 #include <stdarg.h>
 #include <string.h>
 
 
+struct _Geis
+{
+  GeisErrorStack         error_stack;
+  GeisSubBag             subscription_bag;
+  GeisBackendMultiplexor backend_multiplexor;
+  GeisBackend            backend;
+};
+
 
 /**
  * Creates a new empty Geis API instance.
@@ -40,7 +51,7 @@
   {
     geis_error_push(NULL, GEIS_STATUS_UNKNOWN_ERROR);
     geis_error("calloc failed");
-    goto error_exit;
+    goto final_exit;
   }
 
   geis->subscription_bag = geis_subscription_bag_new(1);
@@ -50,10 +61,26 @@
     geis_error("creation of subscroption bag failed");
     free(geis);
     geis = NULL;
-    goto error_exit;
-  }
-
-error_exit:
+    goto unwind_geis;
+  }
+
+  geis->backend_multiplexor = geis_backend_multiplexor_new();
+  if (!geis->backend_multiplexor)
+  {
+    geis_error_push(NULL, GEIS_STATUS_UNKNOWN_ERROR);
+    geis_error("creation of back end multiplexor failed");
+    goto unwind_subscription_bag;
+  }
+  goto final_exit;
+
+unwind_subscription_bag:
+    geis_subscription_bag_delete(geis->subscription_bag);
+
+unwind_geis:
+    free(geis);
+    geis = NULL;
+
+final_exit:
   return geis;
 }
 
@@ -70,14 +97,27 @@
     {
       geis_debug("initializing GEIS server");
     }
-    else if (0 == strcmp(init_arg_name, "geis-test-fixture"))
+    else if (0 == strcmp(init_arg_name, GEIS_INIT_UTOUCH_MOCK_ENGINE))
     {
-      geis_debug("initializing GEIS test fixture");
-      geis->is_test_fixture = GEIS_TRUE;
+      if (NULL != geis->backend)
+      {
+	geis_error("multiple back ends requested, only using %s",\
+	           geis_backend_name(geis->backend));
+      }
+      else
+      {
+	geis_debug("initializing GEIS test fixture");
+	geis->backend = geis_backend_new_test_fixture(geis);
+      }
     }
 
     init_arg_name = va_arg(varargs, GeisString);
   }
+
+  if (NULL == geis->backend)
+  {
+    geis_debug("initializing default GEIS back end");
+  }
 }
 
 
@@ -110,6 +150,11 @@
   {
     return GEIS_STATUS_BAD_ARGUMENT;
   }
+
+  if (geis->backend)
+    geis_backend_delete(geis->backend);
+  geis_backend_multiplexor_delete(geis->backend_multiplexor);
+  geis_subscription_bag_delete(geis->subscription_bag);
   free(geis);
   return GEIS_STATUS_SUCCESS;
 }
@@ -127,8 +172,16 @@
 
   if (0 == strcmp(configuration_item_name, GEIS_CONFIGURATION_FD))
   {
-    /* status = GEIS_STATUS_SUCCESS; */
-  };
+    *(int*)configuration_item_value
+        = geis_backend_multiplexor_fd(geis->backend_multiplexor);
+    status = GEIS_STATUS_SUCCESS; 
+  }
+  else if (0 == strcmp(configuration_item_name, GEIS_CONFIG_UTOUCH_MAX_EVENTS))
+  {
+    *(int*)configuration_item_value
+        = geis_backend_multiplexor_max_events_per_pump(geis->backend_multiplexor);
+    status = GEIS_STATUS_SUCCESS; 
+  }
 
   return status;
 }
@@ -142,7 +195,22 @@
                        GeisString  configuration_item_name,
                        void       *configuration_item_value)
 {
-  return GEIS_STATUS_UNKNOWN_ERROR;
+  GeisStatus status = GEIS_STATUS_NOT_SUPPORTED;
+
+  if (0 == strcmp(configuration_item_name, GEIS_CONFIG_UTOUCH_MAX_EVENTS))
+  {
+    int max_events = *(int *)configuration_item_value;
+    geis_backend_multiplexor_set_max_events_per_pump(geis->backend_multiplexor,
+                                                     max_events);
+    status = GEIS_STATUS_SUCCESS; 
+  }
+  return status;
+}
+
+
+GeisErrorStack *geis_error_stack(Geis geis)
+{
+  return &geis->error_stack;
 }
 
 
 
=== added file 'libutouch-geis/geis_backend.c'
--- libutouch-geis/geis_backend.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_backend.c	2010-12-02 19:24:57 +0000
@@ -0,0 +1,65 @@
+/**
+ * @file geis_backend.c
+ * @brief internal GEIS back end base class implementation
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#include "geis_backend.h"
+#include "geis_backend_protected.h"
+
+#include "geis_logging.h"
+#include <stdlib.h>
+#include <string.h>
+
+
+/*
+ * Initializes the base portion of the back end.
+ */
+void
+geis_backend_init_base(GeisBackend       be_base,
+                       GeisBackendVtable be_vtbl,
+                       GeisString        be_name)
+{
+  be_base->be_name = strdup(be_name);
+  be_base->be_vtbl = be_vtbl;
+}
+
+
+/*
+ * Destroys the back end.
+ */
+void
+geis_backend_delete(GeisBackend be)
+{
+  if (be)
+  {
+    free((char *)be->be_name);
+    be->be_vtbl->finalize(be);
+  }
+  geis_debug("%s back end destroyed", geis_backend_name(be));
+}
+
+
+/*
+ * Gets the name of the back end (RTTI).
+ */
+GeisString
+geis_backend_name(GeisBackend be)
+{
+  return be->be_name;
+}
+
 
=== added file 'libutouch-geis/geis_backend.h'
--- libutouch-geis/geis_backend.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_backend.h	2010-12-02 19:24:57 +0000
@@ -0,0 +1,56 @@
+/**
+ * @file geis_backend.h
+ * @brief internal GEIS back end base class public interface
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#ifndef GEIS_BACKEND_H_
+#define GEIS_BACKEND_H_
+
+#include "geis/geis.h"
+
+/**
+ * Provides a virtual "base class" for various GEIS back ends.
+ *
+ * The GEIS is an API that implements the facade pattern over some number of
+ * actual "back end" implementations.  Most internal operations of teh API are
+ * performed through this "virtual base class" interface rather than through the
+ * concrete back ends (isn;t object-oriented programming great?).
+ */
+typedef struct _GeisBackend *GeisBackend;
+
+
+/**
+ * Destroys the back end.
+ *
+ * @parameter[in] be  The back end.
+ *
+ * This function behaves like a virtual destructor and chains through to the
+ * concrete destructor call.
+ */
+void geis_backend_delete(GeisBackend be);
+
+/**
+ * Gets the name of the back end.
+ *
+ * @parameter[in] be  The back end.
+ *
+ * This accessor is useful for diagnostics.
+ */
+GeisString geis_backend_name(GeisBackend be);
+
+#endif /* GEIS_BACKEND_H_ */
 
=== added file 'libutouch-geis/geis_backend_multiplexor.c'
--- libutouch-geis/geis_backend_multiplexor.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_backend_multiplexor.c	2010-12-02 19:24:57 +0000
@@ -0,0 +1,203 @@
+/**
+ * @file geis_backend_multiplexor.c
+ * @brief internal GEIS backend multiplexor implementation
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#include "geis_config.h"
+#include "geis_backend_multiplexor.h"
+
+#include <errno.h>
+#include "geis_logging.h"
+#include <stdlib.h>
+#include <string.h>
+#include <sys/epoll.h>
+
+
+struct _GeisBackendMultiplexor
+{
+  int mx_fd;
+  int mx_max_events_per_pump;
+};
+
+typedef struct _CallbackInfo
+{
+  int                         fd;
+  GeisBackendFdEventCallback  callback;
+  void                       *context;
+} *CallbackInfo;
+
+
+/**
+ * Creates a new backend multiplexor.
+ */
+GeisBackendMultiplexor
+geis_backend_multiplexor_new()
+{
+  GeisBackendMultiplexor mx = calloc(1, sizeof(struct _GeisBackendMultiplexor));
+  if (!mx)
+  {
+    geis_error("failed to allocate backend multiplexor");
+  }
+  else
+  {
+    mx->mx_fd = epoll_create1(EPOLL_CLOEXEC);
+    if (mx->mx_fd < 0)
+    {
+      geis_error("error %d creating backend multiplexor: %s",
+                 errno, strerror(errno));
+      free(mx);
+    }
+    mx->mx_max_events_per_pump = GEIS_BE_MX_DEFAULT_EVENTS_PER_PUMP;
+  }
+
+  return mx;
+}
+
+
+/**
+ * Destroys an backend multiplexor.
+ */
+void
+geis_backend_multiplexor_delete(GeisBackendMultiplexor mx)
+{
+  free(mx);
+}
+
+
+/**
+ * Adds a file descriptor to an backend multiplexor.
+ */
+void
+geis_backend_multiplexor_add_fd(GeisBackendMultiplexor      mx,
+                                int                         fd,
+                                GeisBackendFdEventCallback  callback,
+                                void                       *context)
+{
+  int status;
+  struct epoll_event ev;
+
+  CallbackInfo callback_info = calloc(1, sizeof(struct _CallbackInfo));
+  if (!callback_info)
+  {
+    geis_error("failed to allocate callback info structure");
+    return;
+  }
+
+  callback_info->fd       = fd;
+  callback_info->callback = callback;
+  callback_info->context  = context;
+
+  ev.events = EPOLLIN;
+  ev.data.ptr = callback_info;
+  status = epoll_ctl(mx->mx_fd, EPOLL_CTL_ADD, fd, &ev);
+  if (status < 0)
+  {
+    geis_error("error %d multiplexing fd %d: %s",
+               errno, fd, strerror(errno));
+  }
+}
+
+
+/**
+ * Removes a file descriptor from a backend multiplexor.
+ *
+ * @todo free callback_info
+ */
+void
+geis_backend_multiplexor_remove_fd(GeisBackendMultiplexor mx, int fd)
+{
+  int status = epoll_ctl(mx->mx_fd, EPOLL_CTL_DEL, fd, NULL);
+  if (status < 0)
+  {
+    geis_error("error %d multiplexing fd %d: %s",
+               errno, fd, strerror(errno));
+  }
+}
+
+
+/**
+ * Gets the single file descriptor of the backend multiplexir itself.
+ */
+int
+geis_backend_multiplexor_fd(GeisBackendMultiplexor mx)
+{
+  return mx->mx_fd;
+}
+
+
+/**
+ * gets the maximum number of fd events per pump.
+ */
+int
+geis_backend_multiplexor_max_events_per_pump(GeisBackendMultiplexor mx)
+{
+  return mx->mx_max_events_per_pump;
+}
+
+
+/**
+ * Sets the maximum number of fd events processed per pump.
+ */
+void
+geis_backend_multiplexor_set_max_events_per_pump(GeisBackendMultiplexor mx,
+                                                 int max_events_per_pump)
+{
+  mx->mx_max_events_per_pump = max_events_per_pump;
+}
+
+
+/**
+ * Dispatches events on the multiplexed file descriptors.
+ */
+GeisStatus
+geis_backend_multiplexor_pump(GeisBackendMultiplexor mx)
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  int i;
+  int processed_event_count = 0;
+  int available_event_count = 1;
+  struct epoll_event events[4];
+
+  while (available_event_count > 0
+      && processed_event_count < mx->mx_max_events_per_pump)
+  {
+    available_event_count = epoll_wait(mx->mx_fd, events, 4, 0);
+    if (available_event_count < 0)
+    {
+      geis_error("error %d in epoll_wait: %s", errno, strerror(errno));
+      goto error_exit;
+    }
+
+    for (i = 0; i < available_event_count; ++i)
+    {
+      CallbackInfo callback_info = (CallbackInfo)events[i].data.ptr;
+      callback_info->callback(callback_info->fd,
+                              GEIS_BE_MX_READ_AVAILABLE,
+                              callback_info->context);
+      ++processed_event_count;
+    }
+  }
+  if (available_event_count)
+    status = GEIS_STATUS_CONTINUE;
+  else
+    status = GEIS_STATUS_SUCCESS;
+
+error_exit:
+  return status;
+}
+
 
=== added file 'libutouch-geis/geis_backend_multiplexor.h'
--- libutouch-geis/geis_backend_multiplexor.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_backend_multiplexor.h	2010-12-02 19:24:57 +0000
@@ -0,0 +1,129 @@
+/**
+ * @file geis_backend_multiplexor.h
+ * @brief internal GEIS backend multiplexor interface
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#ifndef GEIS_BACKEND_MULTIPLEXOR_H_
+#define GEIS_BACKEND_MULTIPLEXOR_H_
+
+#include "geis/geis.h"
+
+
+/**
+ * Multiplexes back end events into a single notification file descriptor.
+ *
+ * The GEIS API presents a single file descriptor to the application to watch
+ * for activity notification.  A back end may be monitoring activity on more
+ * than one file descriptor.  The multiplexor combines these requirements.
+ */
+typedef struct _GeisBackendMultiplexor *GeisBackendMultiplexor;
+
+/**
+ * Indicates the type of fd event that occurred on a multiplexed descriptor.
+ */
+typedef enum _GeisBackendMultiplexorEvent
+{
+  GEIS_BE_MX_READ_AVAILABLE,
+  GEIS_BE_MX_WRITE_AVAILABLE
+} GeisBackendMultiplexorEvent;
+
+/**
+ * Handles events occurring on multiplexed file descriptors.
+ *
+ * Back ends must provide a callback with this signature to the multiplexor.
+ */
+typedef void (*GeisBackendFdEventCallback)(int                          fd,
+                                           GeisBackendMultiplexorEvent  event,
+                                           void                        *context);
+
+/**
+ * Constructs a new back end multiplexor.
+ */
+GeisBackendMultiplexor geis_backend_multiplexor_new();
+
+/**
+ * A reasonable default value for the max_events_per_pump parameter to
+ * geis_backend_multiplexor_new().
+ */
+#define GEIS_BE_MX_DEFAULT_EVENTS_PER_PUMP  16
+
+/**
+ * Destroys a back end multiplexor.
+ *
+ * @param[in] mx  The back end multiplexor to destroy.
+ */
+void geis_backend_multiplexor_delete(GeisBackendMultiplexor mx);
+
+/**
+ * Adds a file descriptor to a back end multiplexor.
+ *
+ * @param[in] mx  The back end multiplexor.
+ * @param[in] fd  The file descriptor to add.
+ */
+void geis_backend_multiplexor_add_fd(GeisBackendMultiplexor      mx,
+                                     int                         fd,
+                                     GeisBackendFdEventCallback  callback,
+                                     void                       *context);
+
+/**
+ * Removes a file descriptor from a back end multiplexor.
+ *
+ * @param[in] mx  The back end multiplexor.
+ * @param[in] fd  The file descriptor to remove.
+ */
+void geis_backend_multiplexor_remove_fd(GeisBackendMultiplexor mx,
+                                        int                    fd);
+
+/**
+ * Gets the file descriptor of the back end multiplexor.
+ *
+ * @param[in] mx  The back end multiplexor.
+ */
+int geis_backend_multiplexor_fd(GeisBackendMultiplexor mx);
+
+/**
+ * Gets the maximum number of fd events per pump.
+ *
+ * @param[in] mx                   The back end multiplexor.
+ */
+int geis_backend_multiplexor_max_events_per_pump(GeisBackendMultiplexor mx);
+
+/**
+ * Sets the maximum fd events per pump of the multiplexor.
+ *
+ * @param[in] mx                   The back end multiplexor.
+ * @param[in] max_events_per_pump  The maximum number of fd events pumped
+ *                                 per call of geis_backend_multiplexor_pump().
+ *
+ * This value is tunable to accommodate different back ends and
+ * application/toolkit requirements.
+ */
+void geis_backend_multiplexor_set_max_events_per_pump(GeisBackendMultiplexor mx,
+                                                      int max_events_per_pump);
+
+/**
+ * Exercises the back end multiplexor.
+ *
+ * @param[in] mx  The back end multiplexor.
+ *
+ * Dispatches any events on multiplexed file descriptors to their assciated
+ * handlers.
+ */
+GeisStatus geis_backend_multiplexor_pump(GeisBackendMultiplexor mx);
+
+#endif /* GEIS_BACKEND_MULTIPLEXOR_H_ */
 
=== added file 'libutouch-geis/geis_backend_protected.h'
--- libutouch-geis/geis_backend_protected.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_backend_protected.h	2010-12-02 19:24:57 +0000
@@ -0,0 +1,61 @@
+/**
+ * @file geis_backend_protected.h
+ * @brief internal GEIS back end base class "protected" interface
+ *
+ * This file contains the implementation interface for the various GEIS v2 back
+ * ends.
+ */
+
+/*
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#ifndef GEIS_BACKEND_PROTECTED_H_
+#define GEIS_BACKEND_PROTECTED_H_
+
+#include "geis/geis.h"
+#include "geis_backend.h"
+
+
+/**
+ * The custom dispatch table for "derived" GEIS v2 backends.
+ */
+typedef struct _GeisBackendVtable
+{
+  void (* finalize)(GeisBackend);
+} *GeisBackendVtable;
+
+/**
+ * The "base" class of all the GEIS v2 backends.
+ */
+struct _GeisBackend {
+  GeisString        be_name;
+  GeisBackendVtable be_vtbl;
+};
+
+
+/**
+ * Initializes the base portion of the GEIS v2 backends.
+ *
+ * @param[in] be_base  The GeisBackend portion of the back end object.
+ * @param[in] be_vtbl  An initialized GeisBackendVtable.
+ * @param[in] be_name  The name of the back end.
+ */
+void geis_backend_init_base(GeisBackend        be_base,
+                            GeisBackendVtable  be_vtbl,
+                            GeisString         be_name);
+
+#endif /* GEIS_BACKEND_PROTECTED_H_ */
 
=== added file 'libutouch-geis/geis_backend_test_fixture.c'
--- libutouch-geis/geis_backend_test_fixture.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_backend_test_fixture.c	2010-12-02 19:24:57 +0000
@@ -0,0 +1,63 @@
+/**
+ * @file geis_backend_test_fixture.c
+ * @brief GEIS mock back end test fixture implementation
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#include "geis_backend.h"
+#include "geis_backend_protected.h"
+
+#include "geis_logging.h"
+#include <stdlib.h>
+
+
+typedef struct _GeisBackendTestFixture
+{
+  struct _GeisBackend  tf_base;
+} *GeisBackendTestFixture;
+
+
+static void 
+geis_backend_finalize(GeisBackend be)
+{
+  GeisBackendTestFixture tf __attribute__((unused)) = (GeisBackendTestFixture)be;
+}
+
+
+static struct _GeisBackendVtable tf_vtbl = {
+  geis_backend_finalize
+};
+
+GeisBackend
+geis_backend_new_test_fixture(Geis geis __attribute__((unused)))
+{
+  GeisBackendTestFixture tf = calloc(1, sizeof(struct _GeisBackendTestFixture));
+  if (!tf)
+  {
+    geis_error("failed to allocate GEIS back end test fixture");
+    goto nomem;
+  }
+
+  geis_backend_init_base(&tf->tf_base, &tf_vtbl, "GEIS2 test fixture");
+
+  geis_debug("%s back end created", geis_backend_name(&tf->tf_base));
+
+nomem:
+  return (GeisBackend)tf;
+}
+
+
 
=== added file 'libutouch-geis/geis_backend_test_fixture.h'
--- libutouch-geis/geis_backend_test_fixture.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_backend_test_fixture.h	2010-12-02 19:24:57 +0000
@@ -0,0 +1,35 @@
+/**
+ * @file geis_backend_test_fixture.h
+ * @brief internal GEIS test fixture back end class
+ *
+ * Copyright 2010 Canonical Ltd.
+ *
+ * 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 3 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 program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+ */
+#ifndef GEIS_BACKEND_TEST_FIXTURE_H_
+#define GEIS_BACKEND_TEST_FIXTURE_H_
+
+#include "geis/geis.h"
+
+/**
+ * Constructs a new GEIS Test Fuixture back end.
+ *
+ * @param[in] geis The API instance the back end will run in.
+ *
+ * The Test Fixture back end is used in unit tests.
+ */
+GeisBackend geis_backend_new_test_fixture(Geis geis);
+
+#endif /* GEIS_BACKEND_TEST_FIXTURE_H_ */
 
=== modified file 'libutouch-geis/geis_error.c'
--- libutouch-geis/geis_error.c	2010-11-28 00:41:24 +0000
+++ libutouch-geis/geis_error.c	2010-12-02 19:24:57 +0000
@@ -74,7 +74,7 @@
 {
   if (geis)
   {
-    geis_error_stack_clear(&geis->error_stack);
+    geis_error_stack_clear(geis_error_stack(geis));
   }
   else
   {
@@ -88,7 +88,7 @@
 {
   if (geis)
   {
-    geis_error_stack_push(&geis->error_stack, code);
+    geis_error_stack_push(geis_error_stack(geis), code);
   }
   else
   {
@@ -102,7 +102,7 @@
 {
   if (geis)
   {
-    return geis->error_stack.error_count;
+    return geis_error_stack(geis)->error_count;
   }
   else
   {
@@ -117,7 +117,7 @@
   GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
   if (geis)
   {
-    status = geis_error_stack_get(&geis->error_stack, index);
+    status = geis_error_stack_get(geis_error_stack(geis), index);
   }
   else
   {
 
=== modified file 'libutouch-geis/geis_private.h'
--- libutouch-geis/geis_private.h	2010-11-29 02:16:02 +0000
+++ libutouch-geis/geis_private.h	2010-12-02 19:24:57 +0000
@@ -27,13 +27,10 @@
 #include "geis_subscription.h"
 
 
-struct _Geis
-{
-  GeisBoolean    is_test_fixture;
-  GeisErrorStack error_stack;
-  GeisSubBag     subscription_bag;
-};
-
+/**
+ * Gets the error stack drom the geis object.
+ */
+GeisErrorStack *geis_error_stack(Geis geis);
 
 /**
  * Gets the subscription container from the geis object.
 
=== modified file 'testsuite/geis2/check_config.c'
--- testsuite/geis2/check_config.c	2010-11-25 03:14:17 +0000
+++ testsuite/geis2/check_config.c	2010-12-02 19:24:57 +0000
@@ -12,7 +12,7 @@
 static void
 construct_geis()
 {
-  geis = geis_new("geis-test-fixture", NULL);
+  geis = geis_new(GEIS_INIT_UTOUCH_MOCK_ENGINE, NULL);
 }
 
 /* fixture teardown */
@@ -37,7 +37,7 @@
 START_TEST(get_fail)
 {
   int fd = -1;
-  GeisStatus status = geis_get_configuration(geis, 1234, &fd);
+  GeisStatus status = geis_get_configuration(geis, "no such configuration", &fd);
   fail_unless(status == GEIS_STATUS_NOT_SUPPORTED,
               "unexpected return status from geis_get_configuration()");
 }
 
=== modified file 'testsuite/geis2/check_error_codes.c'
--- testsuite/geis2/check_error_codes.c	2010-11-21 17:00:48 +0000
+++ testsuite/geis2/check_error_codes.c	2010-12-02 19:24:57 +0000
@@ -9,6 +9,8 @@
 START_TEST(error_codes)
 {
   GeisStatus error = GEIS_STATUS_SUCCESS ;
+  error = GEIS_STATUS_CONTINUE;
+  error = GEIS_STATUS_EMPTY;
   error = GEIS_STATUS_NOT_SUPPORTED;
   error = GEIS_STATUS_BAD_ARGUMENT;
   error = GEIS_STATUS_UNKNOWN_ERROR;
 
=== modified file 'testsuite/geis2/check_geis_new.c'
--- testsuite/geis2/check_geis_new.c	2010-11-23 03:31:21 +0000
+++ testsuite/geis2/check_geis_new.c	2010-12-02 19:24:57 +0000
@@ -8,7 +8,7 @@
 /* compile-time test to ensure required types are defined */
 START_TEST(geis_new_and_delete)
 {
-  Geis geis = geis_new("geis-test-fixture", NULL);
+  Geis geis = geis_new(GEIS_INIT_UTOUCH_MOCK_ENGINE, NULL);
   fail_unless(geis != NULL, "failed to create GEIS v2.0 API instance");
 
   GeisStatus status = geis_delete(geis);
 
=== modified file 'testsuite/geis2/check_subscription.c'
--- testsuite/geis2/check_subscription.c	2010-11-29 02:16:02 +0000
+++ testsuite/geis2/check_subscription.c	2010-12-02 19:24:57 +0000
@@ -14,7 +14,7 @@
 static void
 construct_geis()
 {
-  g_geis = geis_new("geis-test-fixture", NULL);
+  g_geis = geis_new(GEIS_INIT_UTOUCH_MOCK_ENGINE, NULL);
 }
 
 /* fixture teardown */
 
=== modified file 'testsuite/libutouch-geis/Makefile.am'
--- testsuite/libutouch-geis/Makefile.am	2010-11-29 02:16:02 +0000
+++ testsuite/libutouch-geis/Makefile.am	2010-12-02 19:24:57 +0000
@@ -32,6 +32,7 @@
 
 check_geis2_internals_SOURCES = \
 	check_attr.c \
+	check_backend_multiplexor.c \
 	check_error_reporting.c \
 	check_subscription.c \
 	check_geis2_internals.c
 
=== added file 'testsuite/libutouch-geis/check_backend_multiplexor.c'
--- testsuite/libutouch-geis/check_backend_multiplexor.c	1970-01-01 00:00:00 +0000
+++ testsuite/libutouch-geis/check_backend_multiplexor.c	2010-12-02 19:24:57 +0000
@@ -0,0 +1,127 @@
+/**
+ * internal unit tests for the uTouch GEIS v2.0 backend_multiplexor module
+ */
+#include <check.h>
+
+#include "geis/geis.h"
+#include "libutouch-geis/geis_backend_multiplexor.h"
+#include <stdio.h>
+#include <sys/select.h>
+#include <unistd.h>
+
+
+/* fixtures */
+static GeisBackendMultiplexor g_mx;
+
+/* fixture setup */
+static void
+construct_mx()
+{
+  g_mx = geis_backend_multiplexor_new();
+}
+
+/* fixture teardown */
+static void
+destroy_mx()
+{
+  geis_backend_multiplexor_delete(g_mx);
+}
+
+static void
+testcase_event_callback(int fd, GeisBackendMultiplexorEvent event, void *context)
+{
+  char buf[2];
+  (void)read(fd, buf, 1);
+  *(int *)context += 1; 
+}
+
+
+/* verify bag construction/destruction */
+START_TEST(construction)
+{
+  construct_mx();
+  fail_unless(g_mx != NULL, "failed to create backend_multiplexor");
+  fail_unless(geis_backend_multiplexor_fd(g_mx) >= 0, "invalid MX fd");
+  fail_unless(geis_backend_multiplexor_max_events_per_pump(g_mx) == GEIS_BE_MX_DEFAULT_EVENTS_PER_PUMP, "unexpected max fd per pump value");
+  destroy_mx();
+}
+END_TEST
+
+
+/* verify multiplexor wait */
+START_TEST(mx_wait)
+{
+  int pfd[2];
+  int mx_fd = geis_backend_multiplexor_fd(g_mx);
+  int called = 0;
+  int status = 0;
+  int first_time = 1;
+
+  (void)pipe(pfd);
+  geis_backend_multiplexor_add_fd(g_mx, pfd[0], testcase_event_callback, &called);
+
+  while (1)
+  {
+    fd_set fds;
+    FD_ZERO(&fds);
+    FD_SET(mx_fd, &fds);
+
+    struct timeval tm;
+    tm.tv_sec = 0;
+    tm.tv_usec = 5000;
+
+    status = select(mx_fd+1, &fds, NULL, NULL, &tm);
+    fail_if(status < 0, "error in select");
+    if (status < 0)
+    {
+      break;
+    }
+    else if (0 == status)
+    {
+      fprintf(stderr, "select timeout\n");
+      fail_unless(first_time, "select timed out before read");
+      if (!first_time)
+      {
+	break;
+      }
+      first_time = 0;
+      (void)write(pfd[1], "1", 1);
+    }
+    else
+    {
+      geis_backend_multiplexor_pump(g_mx);
+      break;
+    }
+  }
+
+  fail_if(called == 0, "MX event callback not called");
+  fail_if(called >  1, "MX event callback called too many times");
+}
+END_TEST
+
+START_TEST(mx_config)
+{
+  geis_backend_multiplexor_set_max_events_per_pump(g_mx, 24);
+  fail_unless(geis_backend_multiplexor_max_events_per_pump(g_mx) == 24,
+              "unexpected max fd per pump value");
+}
+END_TEST
+
+/* boilerplate */
+Suite *
+make_backend_multiplexor_suite()
+{
+  Suite *s = suite_create("utouch-geis2-backend-multiplexor");
+
+  TCase *create = tcase_create("backend-multiplexor-creation");
+  tcase_add_test(create, construction);
+  suite_add_tcase(s, create);
+
+  TCase *usage = tcase_create("backend-multiplexor-usage");
+  tcase_add_checked_fixture(usage, construct_mx, destroy_mx);
+  tcase_add_test(usage, mx_wait);
+  suite_add_tcase(s, usage);
+
+  return s;
+}
+
 
=== modified file 'testsuite/libutouch-geis/check_geis2_internals.c'
--- testsuite/libutouch-geis/check_geis2_internals.c	2010-11-29 02:16:02 +0000
+++ testsuite/libutouch-geis/check_geis2_internals.c	2010-12-02 19:24:57 +0000
@@ -6,6 +6,7 @@
 extern Suite *make_error_reporting_suite();
 extern Suite *make_attr_suite();
 extern Suite *make_subscription_suite();
+extern Suite *make_backend_multiplexor_suite();
 
 
 int
@@ -19,6 +20,7 @@
   srunner_add_suite(sr, make_error_reporting_suite());
   srunner_add_suite(sr, make_attr_suite());
   srunner_add_suite(sr, make_subscription_suite());
+  srunner_add_suite(sr, make_backend_multiplexor_suite());
 
   srunner_set_log(sr, "geis2_internals.log");
   srunner_run_all(sr, CK_NORMAL);
 
=== modified file 'testsuite/libutouch-geis/check_subscription.c'
--- testsuite/libutouch-geis/check_subscription.c	2010-11-29 02:16:02 +0000
+++ testsuite/libutouch-geis/check_subscription.c	2010-12-02 19:24:57 +0000
@@ -16,7 +16,7 @@
 static void
 construct_bag()
 {
-  g_geis = geis_new("geis-test-fixture", NULL);
+  g_geis = geis_new(GEIS_INIT_UTOUCH_MOCK_ENGINE, NULL);
   g_sub_bag = geis_subscription_bag_new(1);
 }