Merge lp:~oif-team/geis/event-control-functions into lp:geis

[Stephen M. Webb]

o adds a basic GeisEvent module

o adds an internal event queue module

o adds the event control functions to the Geis module

This resubmission incorporates Chase's requested changes (except #2, which was unclear).

This resubmission also incorporates a design change in the internal queueing (separate input and output queues) that came out of work on bug #674682. Better to put it in now on first commit than commit a known flaw and change it again later.

[Chase Douglas (chasedouglas)]

1. I would remove the geis_event_delete calls until it's implemented. I don't like seeing "#if 0" :). If you want to note something that should be changed in the future, I think a "FIXME: <blah>" is better. It gives context as to what is needed.

2. geis_event_queue_push allocates a GeisEvent on the stack and copies the event passed in. Then, the event is copied once more into the GeisEventQueueNode. The stack allocation and copying of the GeisEvent into the function is unnecessary. A pointer should be passed instead.

3. The event queue is a queue, not a stack. Queue semantics should be used, such as enqueue and dequeue. Using push and pop confuses me until I remember that it's a queue :).

4. geis_event_queue_front copies data into a geis event. Why not just return a pointer to the event? This would cut down on extra allocating and copying.

5. Imo, a cleaner interface is a dequeue function that returns the event if available and removes it from the queue. This requires one function call instead of two to retrieve the event and remove it.

review: Needs Fixing

[Henrik Rydberg (rydberg)]

There is a geis_event_attr_by_name(), but is there a way to retrieve the index corresponding to the name?

It would be good if the geis_event_queue_dequeue() docs state who owns the pointer after the call, and/or for how long the pointer is valid.

review: Needs Information

[lp:~oif-team/geis/event-control-functions]

116. By Stephen M. Webb on 2010-12-13

Renamed event queue functions.

[Stephen M. Webb (bregma)]

> There is a geis_event_attr_by_name(), but is there a way to retrieve the index corresponding to
> the name?

No, the GeisEvent is effectively an associative container of attributes and I am not aware of any associative container that provides such functionality. Is there a use case you're thinking of?

> It would be good if the geis_event_queue_dequeue() docs state who owns the pointer after the call,
> and/or for how long the pointer is valid.

OK, I updated the docs to try to explain that the container uses value semantics on the opaque objects and does not control use of those object either before or after their being contained.

[Henrik Rydberg (rydberg)]

On 12/13/2010 03:41 PM, Stephen M. Webb wrote:

>> There is a geis_event_attr_by_name(), but is there a way to retrieve the index corresponding to
>> the name?
>
> No, the GeisEvent is effectively an associative container of attributes

> and I am not aware of any associative container that provides such
> functionality. Is there a use case you're thinking of?

Attributes are being read in abundance in the inner event loop, so some cpu will
be used for the lookup. Since there are two lookup methods, it seems the mapping
between the two is missing, or did I misread something? Usecase-wise, I would
collect the indices of the attributes in question at init, and then use the
indices during event handling. But sure, things will still work as they are,
only less effectively.

Thanks!

[Chase Douglas (chasedouglas)]

I didn't realize the merge proposal had been updated :(.

After reviewing the code again, I realized that GeisEvent is an opaque struct pointer, thus there's no copy overhead I mentioned in my previous review.

The only concern I had that isn't addressed yet is the #if 0. I still would like to see this fixed in time, but it's not worth holding this merge up.

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2010-11-24 16:59:34 +0000
+++ .bzrignore	2010-12-13 14:34:12 +0000
@@ -1,9 +1,9 @@
 **.pdf
+**/Makefile
 *.deps
 *.libs
 */*.la
 */*.lo
-*/Makefile
 *Makefile.in
 aclocal.m4
 autom4te.cache
@@ -23,16 +23,16 @@
 doc/docbook-xsl.css
 doc/geisspec-1.0.html
 geis_config.*
+libtool
 libutouch-geis-xcb/xcb_gesture.xml
 libutouch-geis-xcb/xcb_gesture.[ch]
 libutouch-geis.pc
-libtool
-Makefile
 stamp-*
-testsuite/libutouch-geis/check_geis2_internals
-testsuite/libutouch-geis/*.log
+testsuite/geis1/*.log
 testsuite/geis1/check_geis_internals
-testsuite/geis1/*.log
+testsuite/geis2/*.log
 testsuite/geis2/check_geis2_api
-testsuite/geis2/*.log
 testsuite/geistest/geistest
+testsuite/libutouch-geis/*.log
+testsuite/libutouch-geis/*.xml
+testsuite/libutouch-geis/check_geis2_internals

=== modified file 'ChangeLog'
--- ChangeLog	2010-12-02 19:09:57 +0000
+++ ChangeLog	2010-12-13 14:34:12 +0000
@@ -1,3 +1,58 @@
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Refactored event queue style.
+
+  * libutouch-geis/geis_event_queue.h (geis_event_queue_enqueue): renamed from
+    geis_event_queue_push
+    (geis_event_queue_dequeue): renamed from geis_event_queue_pop
+    changed event output parameter to return value
+  * libutouch-geis/geis_event_queue.c: refactored for above
+  * libutouch-geis/geis.c: refactored for above
+  * testsuite/libutouch-geis/check_event_queue.c: refactored for above
+
+
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Added an event queue.
+
+  * libutouch-geis/geis_event.c: new file
+  * libutouch-geis/geis_event.h: new file
+  * libutouch-geis/geis_event_queue.c: new file
+  * libutouch-geis/geis_event_queue.h: new file
+  * testsuite/libutouch-geis/check_backend_event_posting.c: new test case
+  * testsuite/libutouch-geis/check_event_queue.c: new test case
+  * include/geis/geis.h (GeisEventType): new enum type
+    (geis_event_delete): new function
+    (geis_event_type): new function
+    (geis_event_attr_count): new function
+    (geis_event_attr): new function
+    (geis_event_attr_by_name): new function
+  * libutouch-geis/Makefile.am: added new files
+  * libutouch-geis/geis.c (struct _Geis): added input_event_queue,
+    output_event_queue, and input_signal_pipe members
+    (_default_output_event_callback): new function
+    (_input_event_handler): new function
+    (geis_new_empty): initialized new members
+    (geis_register_event_callback): used _default_output_event_callback
+    (geis_next_event): implemented stubbed-out function
+  * testsuite/libutouch-geis/Makefile.am: added new test cases
+  * testsuite/libutouch-geis/check_geis2_internals.c: added new test cases
+
+
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Added GEIS v2.0 event control functions.
+
+  * include/geis/geis.h (GeisEvent): new type
+    (GeisEventCallback): new type
+    (GEIS_DEFAULT_EVENT_CALLBACK): new constant
+    (geis_register_event_callback): new function
+    (geis_dispatch_events): new function
+    (geis_next_event): new function
+  * libutouch-geis/geis_private.h (geis_post_event): new function
+  * libutouch-geis/geis.c: implemented new functions
+  * libutouch-geis/libutouch-geis.ver: added new symbols
+
 2010-12-02  Stephen M. Webb  <[e-mail]>
 
   Added a back end base and test fixture.

=== modified file 'include/geis/geis.h'
--- include/geis/geis.h	2010-12-02 19:09:57 +0000
+++ include/geis/geis.h	2010-12-13 14:34:12 +0000
@@ -299,7 +299,7 @@
 /* @} */
 
 /**
- * @defgroup geis_config Configuration and Control (GEIS v1.0)
+ * @defgroup geis1_config Configuration and Control (GEIS v1.0)
  * @{
  */
 
@@ -717,6 +717,166 @@
 
 /* @} */
 
+/**
+ * @defgroup geis2_event_control Event Control (GEIS v2.0)
+ *
+ * These functions are used to dispatch events generated from the various other
+ * GEIS components.
+ *
+ * Applications must invoke geis_dispatch_events() from time to time to generate
+ * input device, gesture type, and gesture events.  The GEIS events are then
+ * retrieved either from the internal event queue using the geis_next_event()
+ * call or through an application-supplied callback set through the
+ * geis_register_event_callback() call.
+ *
+ * @{
+ */
+
+typedef enum _GeisEventType
+{ 
+  GEIS_EVENT_TYPE_DEVICE_AVAILABLE         = 1000,
+  GEIS_EVENT_TYPE_DEVICE_UNAVAILABLE       = 1010,
+  GEIS_EVENT_TYPE_GESTURE_TYPE_AVAILABLE   = 2000,
+  GEIS_EVENT_TYPE_GESTURE_TYPE_UNAVAILABLE = 2010,
+  GEIS_EVENT_TYPE_GESTURE_BEGIN            = 3000,
+  GEIS_EVENT_TYPE_GESTURE_UPDATE           = 3010,
+  GEIS_EVENT_TYPE_GESTURE_END              = 3020,
+  GEIS_EVENT_TYPE_ERROR                    = 5000,
+  GEIS_EVENT_TYPE_UNKNOWN                  = 9999
+} GeisEventType;
+
+/**
+ * Opaque pointer to a generic GEIS event.
+ *
+ * Applications must determine the type of the actual event and convert the
+ * opaque pointer to a concrete event pointer, if required.
+ *
+ * Events are created by the GEIS API but must be destroyed by the application.
+ */
+typedef struct _GeisEvent *GeisEvent;
+
+/**
+ * Destroys a GeisEvent.
+ *
+ * @param[in] geis The GeisEvent to destroy.
+ */
+GEIS_API void geis_event_delete(GeisEvent event);
+
+/**
+ * Gets the type of the event.
+ *
+ * @param[in] geis The GeisEvent to destroy.
+ */
+GEIS_API GeisEventType geis_event_type(GeisEvent event);
+
+/**
+ * Gets the number of attributes in the event.
+ *
+ * @param[in] geis The GeisEvent.
+ */
+GEIS_API GeisSize geis_event_attr_count(GeisEvent event);
+
+/**
+ * Gets an indicated attribute from the event.
+ *
+ * @param[in] geis  The GeisEvent.
+ * @param[in] index Indicates the attribute to retrieve.
+ */
+GEIS_API GeisAttr geis_event_attr(GeisEvent event, GeisSize index);
+
+/**
+ * Gets a named attribute from the event.
+ *
+ * @param[in] geis      The GeisEvent.
+ * @param[in] attr_name The name of the attribute to retrieve.
+ */
+GEIS_API GeisAttr geis_event_attr_by_name(GeisEvent event, GeisString attr_name);
+
+/**
+ * The application callback type for the event dispatcher.
+ *
+ * @param[in] geis    the GEIS API instance
+ * @param[in] event   the opaque event pointer
+ * @param[in] context the application-supplied context value
+ */
+typedef void (*GeisEventCallback)(Geis geis, GeisEvent event, void *context);
+
+/**
+ * A special constant indicating the use of the default event callback.
+ */
+#define GEIS_DEFAULT_EVENT_CALLBACK ((GeisEventCallback)0)
+
+/**
+ * Registers an event-handler callback.
+ *
+ * @param[in] geis           the GEIS API instance
+ * @param[in] event_callback the callback to register
+ * @param[in] context        the caller context
+ *
+ * This function registers the callback to be executed whenever a new GeisEvent
+ * is generated.  The default function pushes the GeisEvent onto an internal
+ * queue to be picked up by a call to geis_next_event().
+ *
+ * Calling geis_register_event_callback() with a callback of
+ * GEIS_DEFAULT_EVENT_CALLBACK replaces any registered function wit hthe default
+ * function.
+ *
+ * The callback is executed in the same thread context as the one
+ * geis_dispatch_events() is called from.
+ */
+GEIS_API void geis_register_event_callback(Geis               geis,
+                                           GeisEventCallback  event_callback,
+                                           void              *context);
+
+/**
+ * Pumps the GEIS event loop.
+ *
+ * @param[in]  geis  The GEIS API instance.
+ * @param[out] event An opeaque event object.
+ *
+ * Processes input events until there are no more input events to process and
+ * generates zero or more gesture events, reporting them via the user-supplied
+ * callback or pushing them on the internal event queue for retrieval via the
+ * geis_next_event() call.
+ *
+ * @retval GEIS_STATUS_SUCCESS       The event loop was successfully pumped and
+ *                                   no further events remain to be processed at
+ *                                   this time.
+ *
+ * @retval GEIS_STATUS_CONTINUE      The event loop was successfully pumped but
+ *                                   the system detected there are events
+ *                                   still remaining to be processed.
+ *
+ * @retval GEIS_STATUS_UNKNOWN_ERROR Some error occurred
+ */
+GEIS_API GeisStatus geis_dispatch_events(Geis geis);
+
+/**
+ * Retrieves the next queued GEIS event.
+ *
+ * @param[in]  geis  The GEIS API instance.
+ * @param[out] event The GeisEvent retrieved, if any.
+ *
+ * Pulls the next available GeisEvent from the internal event queue, if any, and
+ * indicates whether there are more events left.
+ *
+ * @retval GEIS_STATUS_SUCCESS       An event was successfully pulled from the
+ *                                   queue and the queue is now empty.
+ *
+ * @retval GEIS_STATUS_CONTINUE      An event was successfully pulled from the
+ *                                   queue and one or more events remain in the
+ *                                   queue.
+ *
+ * @retval GEIS_STATUS_EMPTY         No event was pulled from the queue because
+ *                                   it is empty.  The value of *event remains
+ *                                   unchanged.
+ *
+ * @retval GEIS_STATUS_UNKNOWN_ERROR Some error occurred
+ */
+GEIS_API GeisStatus geis_next_event(Geis geis, GeisEvent *event);
+
+/* @} */
+
 #ifdef __cplusplus
 } // extern "C"
 #endif

=== modified file 'libutouch-geis/Makefile.am'
--- libutouch-geis/Makefile.am	2010-12-02 19:09:57 +0000
+++ libutouch-geis/Makefile.am	2010-12-13 14:34:12 +0000
@@ -26,9 +26,11 @@
 	geis_attr.h                 geis_attr.c \
 	geis_backend.h              geis_backend.c \
 	geis_backend_protected.h \
+	geis_backend_multiplexor.h  geis_backend_multiplexor.c \
 	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_event.h                geis_event.c \
+	geis_event_queue.h          geis_event_queue.c \
 	geis_logging.h              geis_logging.c \
 	geis_subscription.h         geis_subscription.c \
 	geis_private.h              geis.c

=== modified file 'libutouch-geis/geis.c'
--- libutouch-geis/geis.c	2010-12-02 19:09:57 +0000
+++ libutouch-geis/geis.c	2010-12-13 14:34:12 +0000
@@ -21,24 +21,76 @@
 #include "geis_config.h"
 #include "geis_private.h"
 
+#include <errno.h>
 #include "geis_backend.h"
 #include "geis_backend_test_fixture.h"
 #include "geis_backend_multiplexor.h"
 #include "geis_error.h"
+#include "geis_event_queue.h"
 #include "geis_logging.h"
 #include <stdarg.h>
 #include <string.h>
+#include <unistd.h>
 
 
 struct _Geis
 {
-  GeisErrorStack         error_stack;
-  GeisSubBag             subscription_bag;
-  GeisBackendMultiplexor backend_multiplexor;
-  GeisBackend            backend;
+  GeisErrorStack          error_stack;
+  GeisSubBag              subscription_bag;
+  GeisBackendMultiplexor  backend_multiplexor;
+  GeisBackend             backend;
+  GeisEventQueue          input_event_queue;
+  int                     input_event_signal_pipe[2];
+  GeisEventQueue          output_event_queue;
+  GeisEventCallback       output_event_callback;
+  void                   *output_event_callback_context;
 };
 
 
+/*
+ * The default event callback -- just pushes events on the internal queue
+ */
+static void
+_default_output_event_callback(Geis       geis,
+                               GeisEvent  event,
+                               void      *context __attribute__((unused)))
+{
+  geis_debug("posting output event");
+  geis_event_queue_enqueue(geis->output_event_queue, event);
+}
+
+/*
+ * Filters and transforms raw gesture events into cooked gesture events.
+ *
+ * For now, does nothing except copy from the input queueu to the output queue.
+ */
+static void
+_input_event_handler(int fd, GeisBackendMultiplexorEvent mux_ev, void *context)
+{
+  Geis geis = (Geis)context;
+
+  if (mux_ev == GEIS_BE_MX_READ_AVAILABLE)
+  {
+    GeisEvent event;
+
+    /* clear the input event signal */
+    char buf[2];
+    if (read(fd, buf, 1) != 1)
+    {
+      geis_warning("unexpected number of bytes read from signal pipe");
+    }
+
+    geis_debug("input event available");
+    event = geis_event_queue_dequeue(geis->input_event_queue);
+    if (event)
+    {
+      geis->output_event_callback(geis,
+                                  event,
+                                  geis->output_event_callback_context);
+    }
+  }
+}
+
 /**
  * Creates a new empty Geis API instance.
  */
@@ -71,14 +123,49 @@
     geis_error("creation of back end multiplexor failed");
     goto unwind_subscription_bag;
   }
+
+  geis->input_event_queue = geis_event_queue_new();
+  if (!geis->input_event_queue)
+  {
+    geis_error_push(NULL, GEIS_STATUS_UNKNOWN_ERROR);
+    geis_error("creation of input event queue failed");
+    goto unwind_backend_mux;
+  }
+  if (pipe(geis->input_event_signal_pipe) < 0)
+  {
+    geis_error_push(NULL, GEIS_STATUS_UNKNOWN_ERROR);
+    geis_error("error %d creating input event signal pipe: %s",
+               errno, strerror(errno));
+    goto unwind_input_queue;
+  }
+  geis_backend_multiplexor_add_fd(geis->backend_multiplexor,
+                                  geis->input_event_signal_pipe[0],
+                                  _input_event_handler,
+                                  geis);
+
+  geis->output_event_queue = geis_event_queue_new();
+  if (!geis->output_event_queue)
+  {
+    geis_error_push(NULL, GEIS_STATUS_UNKNOWN_ERROR);
+    geis_error("creation of output event queue failed");
+    goto unwind_input_signal_pipe;
+  }
+  geis->output_event_callback = _default_output_event_callback;
+
   goto final_exit;
 
+unwind_input_signal_pipe:
+  close(geis->input_event_signal_pipe[0]);
+  close(geis->input_event_signal_pipe[1]);
+unwind_input_queue:
+  geis_event_queue_delete(geis->input_event_queue);
+unwind_backend_mux:
+  geis_backend_multiplexor_delete(geis->backend_multiplexor);
 unwind_subscription_bag:
-    geis_subscription_bag_delete(geis->subscription_bag);
-
+  geis_subscription_bag_delete(geis->subscription_bag);
 unwind_geis:
-    free(geis);
-    geis = NULL;
+  free(geis);
+  geis = NULL;
 
 final_exit:
   return geis;
@@ -187,7 +274,7 @@
 }
 
 
-/**
+/*
  * Sets a named configuration item.
  */
 GeisStatus
@@ -208,7 +295,75 @@
 }
 
 
-GeisErrorStack *geis_error_stack(Geis geis)
+/*
+ * Registers an application-supplied event callback.
+ */
+void 
+geis_register_event_callback(Geis               geis,
+                             GeisEventCallback  output_event_callback,
+                             void              *context)
+{
+  if (output_event_callback == GEIS_DEFAULT_EVENT_CALLBACK)
+  {
+    geis->output_event_callback = _default_output_event_callback;
+  }
+  else
+  {
+    geis->output_event_callback = output_event_callback;
+  }
+  geis->output_event_callback_context = context;
+}
+
+
+/*
+ * Pumps the GEIS v2 event loop.
+ */
+GeisStatus
+geis_dispatch_events(Geis geis)
+{
+  GeisStatus status = geis_backend_multiplexor_pump(geis->backend_multiplexor);
+  return status;
+}
+
+
+/*
+ * Posts an event through the API.
+ *
+ * Pushes the new event onto the input event queue and signals that a new event
+ * has arrived.
+ */
+void
+geis_post_event(Geis geis, GeisEvent event)
+{
+  geis_event_queue_enqueue(geis->input_event_queue, event);
+  if (write(geis->input_event_signal_pipe[1], "1", 1) != 1)
+  {
+    geis_error("error %d writing input event signal: %s", errno, strerror(errno));
+  }
+}
+
+
+/*
+ * Pulls the next event off the queue.
+ */
+GeisStatus
+geis_next_event(Geis geis, GeisEvent *event)
+{
+  GeisStatus status = GEIS_STATUS_EMPTY;
+  *event = geis_event_queue_dequeue(geis->output_event_queue);
+  if (*event)
+  {
+    status = geis_event_queue_is_empty(geis->output_event_queue)
+           ? GEIS_STATUS_SUCCESS
+           : GEIS_STATUS_CONTINUE;
+  }
+
+  return status;
+}
+
+
+GeisErrorStack *
+geis_error_stack(Geis geis)
 {
   return &geis->error_stack;
 }

=== modified file 'libutouch-geis/geis_attr.c'
--- libutouch-geis/geis_attr.c	2010-11-26 18:22:53 +0000
+++ libutouch-geis/geis_attr.c	2010-12-13 14:34:12 +0000
@@ -123,6 +123,22 @@
 
 
 GeisAttr
+geis_attr_bag_attr(GeisAttrBag bag, GeisSize index)
+{
+  GeisAttr attr = NULL;
+  if (index >= bag->attr_count)
+  {
+    geis_error("index out of range");
+  }
+  else
+  {
+    return bag->attr_store[index];
+  }
+  return attr;
+}
+
+
+GeisAttr
 geis_attr_bag_find(GeisAttrBag bag, GeisString attr_name)
 {
   GeisAttr attr = NULL;

=== modified file 'libutouch-geis/geis_attr.h'
--- libutouch-geis/geis_attr.h	2010-11-26 18:22:53 +0000
+++ libutouch-geis/geis_attr.h	2010-12-13 14:34:12 +0000
@@ -43,6 +43,11 @@
 GeisSize geis_attr_bag_count(GeisAttrBag bag);
 
 /**
+ * Pulls an indicated attr out of a bag.
+ */
+GeisAttr geis_attr_bag_attr(GeisAttrBag bag, GeisSize index);
+
+/**
  * Inserts an attribute in an attribute container.
  */
 GeisStatus geis_attr_bag_insert(GeisAttrBag bag, GeisAttr attr);

=== added file 'libutouch-geis/geis_event.c'
--- libutouch-geis/geis_event.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_event.c	2010-12-13 14:34:12 +0000
@@ -0,0 +1,124 @@
+/**
+ * @file geis_event.c
+ * @brief uTouch GeisEvent module 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/geis.h"
+#include "geis_attr.h"
+#include "geis_logging.h"
+#include <stdlib.h>
+
+
+struct _GeisEvent
+{
+  GeisEventType ev_type;
+  GeisAttrBag   ev_attr_bag;
+};
+
+
+/*
+ * Creates a new event.
+ */
+GeisEvent
+geis_event_new(GeisEventType ev_type)
+{
+  GeisEvent event = calloc(1, sizeof(struct _GeisEvent));
+  if (!event)
+  {
+    geis_error("unable to allocate GeisEvent");
+    goto final_exit;
+  }
+
+  event->ev_type = ev_type;
+  event->ev_attr_bag =  geis_attr_bag_new(4);
+  if (!event->ev_attr_bag)
+  {
+    geis_error("unable to allocate GeisEvent attribute bag");
+    goto unwind_event;
+  }
+  goto final_exit;
+
+unwind_event:
+  free(event);
+final_exit:
+  return event;
+}
+
+
+/*
+ * Destroys an event.
+ */
+void
+geis_event_delete(GeisEvent event)
+{
+  geis_attr_bag_delete(event->ev_attr_bag);
+  free(event);
+}
+
+
+/*
+ * Gets the type of the event.
+ */
+GeisEventType
+geis_event_type(GeisEvent event)
+{
+  return event->ev_type;
+}
+
+
+/*
+ * Gets how many attrs are in the event.
+ */
+GeisSize
+geis_event_attr_count(GeisEvent event)
+{
+  return geis_attr_bag_count(event->ev_attr_bag);
+}
+
+
+/*
+ * Gets an indicated attr.
+ */
+GeisAttr
+geis_event_attr(GeisEvent event, GeisSize index)
+{
+  return geis_attr_bag_attr(event->ev_attr_bag, index);
+}
+
+
+/*
+ * Gets a named attr.
+ */
+GeisAttr
+geis_event_attr_by_name(GeisEvent event, GeisString attr_name)
+{
+  return geis_attr_bag_find(event->ev_attr_bag, attr_name);
+}
+
+
+/*
+ * Adds an attr.
+ */
+GeisStatus
+geis_event_add_attr(GeisEvent event, GeisAttr attr)
+{
+  return geis_attr_bag_insert(event->ev_attr_bag, attr);
+}
+
+

=== added file 'libutouch-geis/geis_event.h'
--- libutouch-geis/geis_event.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_event.h	2010-12-13 14:34:12 +0000
@@ -0,0 +1,41 @@
+/**
+ * @file geis_event.c
+ * @brief Internal interface of the uTouch GeisEvent module
+ *
+ * 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_EVENT_H_
+#define GEIS_EVENT_H_
+
+#include "geis/geis.h"
+
+/**
+ * Creates a new, empty event of type @p type.
+ *
+ * @param[in] type  The type of the event.
+ */
+GeisEvent geis_event_new(GeisEventType type);
+
+/**
+ * Adds an attr to an event.
+ *
+ * @param[in] event  The event.
+ * @param[in] attr   The attr.
+ */
+GeisStatus geis_event_add_attr(GeisEvent event, GeisAttr attr);
+
+#endif /* GEIS_EVENT_H_ */

=== added file 'libutouch-geis/geis_event_queue.c'
--- libutouch-geis/geis_event_queue.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_event_queue.c	2010-12-13 14:34:12 +0000
@@ -0,0 +1,154 @@
+/**
+ * @file geis_event_queue.c
+ * @brief internal uTouch Geis event queue 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_event_queue.h"
+
+#include "geis_logging.h"
+#include <stdlib.h>
+
+
+typedef struct _GeisEventQueueNode *GeisEventQueueNode;
+
+struct _GeisEventQueueNode
+{
+  GeisEventQueueNode eq_next;
+  GeisEvent          eq_event;
+};
+
+struct _GeisEventQueue
+{
+  GeisEventQueueNode eq_front;
+  GeisEventQueueNode eq_back;
+  GeisEventQueueNode eq_pool;
+};
+
+
+/*
+ * Creates a new Geis Event queue.
+ */
+GeisEventQueue
+geis_event_queue_new()
+{
+  GeisEventQueue queue = calloc(1, sizeof(struct _GeisEventQueue));
+  if (!queue)
+  {
+    geis_error("can not allocate event queue");
+  }
+  return queue;
+}
+
+
+/*
+ * Destroys a Geis Event queue.
+ */
+void
+geis_event_queue_delete(GeisEventQueue queue)
+{
+  GeisEventQueueNode node = queue->eq_pool;
+  while (node)
+  {
+    GeisEventQueueNode eq_next = node->eq_next;
+    free(node);
+    node = eq_next;
+  }
+
+  node = queue->eq_front;
+  while (node)
+  {
+    GeisEventQueueNode eq_next = node->eq_next;
+    geis_event_delete(node->eq_event);
+    free(node);
+    node = eq_next;
+  }
+
+  free(queue);
+}
+
+
+/*
+ * Pushes a new event onto the back of the event queue.
+ */
+GeisStatus
+geis_event_queue_enqueue(GeisEventQueue queue, GeisEvent event)
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  GeisEventQueueNode node;
+
+  if (queue->eq_pool)
+  {
+    node = queue->eq_pool;
+    queue->eq_pool = node->eq_next;
+  }
+  else
+  {
+    node = calloc(1, sizeof(struct _GeisEventQueueNode));
+    if (!node)
+    {
+      geis_error("can not allocate event queue node");
+      goto error_exit;
+    }
+  }
+
+  node->eq_event = event;
+  if (!queue->eq_front)
+  {
+    queue->eq_front = node;
+  }
+  if (queue->eq_back)
+  {
+    queue->eq_back->eq_next = node;
+  }
+  queue->eq_back = node;
+  status = GEIS_STATUS_SUCCESS;
+
+error_exit:
+  return status;
+}
+
+
+/*
+ * Indicates if the event queue is empty.
+ */
+GeisBoolean
+geis_event_queue_is_empty(GeisEventQueue queue)
+{
+  return queue->eq_front == NULL;
+}
+
+
+/*
+ * Pops the event off the front of the event queue.
+ */
+GeisEvent
+geis_event_queue_dequeue(GeisEventQueue queue)
+{
+  GeisEvent event = NULL;
+  if (queue->eq_front)
+  {
+    event = queue->eq_front->eq_event;
+
+    GeisEventQueueNode node = queue->eq_front;
+    queue->eq_front = node->eq_next;
+    node->eq_next = queue->eq_pool;
+    queue->eq_pool = node;
+  }
+  return event;
+}
+

=== added file 'libutouch-geis/geis_event_queue.h'
--- libutouch-geis/geis_event_queue.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_event_queue.h	2010-12-13 14:34:12 +0000
@@ -0,0 +1,86 @@
+/**
+ * @file geis_event_queue.h
+ * @brief internal uTouch Geis event queue 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_EVENT_QUEUE_H_
+#define GEIS_EVENT_QUEUE_H_
+
+#include <geis/geis.h>
+
+
+/**
+ * A container for event_queues.
+ *
+ * This is a simple FIFO container for opaque GeisEvent objetcs.
+ *
+ * This container does not asssume ownership of the contained GeisEvents.
+ * Someone creates the events and pushes them into the queue, and someone pulls
+ * the events off the queue and does something with them.
+ *
+ * The current implementation uses a pooled caching strategy for dynamic
+ * allocations to minimize overhead due to high-turnover usage.
+ */
+typedef struct _GeisEventQueue *GeisEventQueue;
+
+
+/**
+ * Creates a new Geis Event queue.
+ */
+GeisEventQueue geis_event_queue_new();
+
+/**
+ * Destroys a Geis Event queue.
+ *
+ * @param[in] queue  The event queue.
+ *
+ * This function empties the queue and destroys any GeisEvents malingering
+ * therein, then destroys the queue itself.
+ */
+void geis_event_queue_delete(GeisEventQueue queue);
+
+/**
+ * Pushes a new event onto the back of the event queue.
+ *
+ * @param[in] queue  The event queue.
+ *
+ * @retval GEIS_STATUS_SUCCESS        Normal successful completion.
+ *
+ * @retval GEIS_STATUS_UNKNOWN_ERROR  Something bad happened.
+ */
+GeisStatus geis_event_queue_enqueue(GeisEventQueue queue, GeisEvent event);
+
+/**
+ * Indicates if an event queue is empty.
+ *
+ * @param[in]  queue  The event queue.
+ *
+ * @returns GEIS_TRUE if the queue contains no events, GEIS_FALSE otherwise.
+ */
+GeisBoolean geis_event_queue_is_empty(GeisEventQueue queue);
+
+/**
+ * Pops the event off the front of the queue.
+ *
+ * @param[in] queue  The event queue.
+ *
+ * @returns the next GeisEvent or NULL of the queue is empty.
+ */
+GeisEvent geis_event_queue_dequeue(GeisEventQueue queue);
+
+#endif /* GEIS_EVENT_QUEUE_H_ */

=== modified file 'libutouch-geis/geis_private.h'
--- libutouch-geis/geis_private.h	2010-11-29 19:22:34 +0000
+++ libutouch-geis/geis_private.h	2010-12-13 14:34:12 +0000
@@ -28,14 +28,27 @@
 
 
 /**
- * Gets the error stack drom the geis object.
+ * Gets the error stack from the geis object.
+ *
+ * @param[in] geis  The API instance.
  */
 GeisErrorStack *geis_error_stack(Geis geis);
 
 /**
  * Gets the subscription container from the geis object.
+ *
+ * @param[in] geis  The API instance.
  */
 GeisSubBag geis_subscription_bag(Geis geis);
 
 
+/**
+ * Posts a new event through the API.
+ *
+ * @param[in] geis  The API instance.
+ * @param[in] event The GEIS event.
+ */
+void geis_post_event(Geis geis, GeisEvent event);
+
+
 #endif /* GEIS_PRIVATE_H_ */

=== modified file 'libutouch-geis/libutouch-geis.ver'
--- libutouch-geis/libutouch-geis.ver	2010-11-29 02:16:02 +0000
+++ libutouch-geis/libutouch-geis.ver	2010-12-13 14:34:12 +0000
@@ -20,11 +20,14 @@
     geis_attr_value_to_integer;
     geis_attr_value_to_string;
     geis_delete;
+    geis_dispatch_events;
     geis_error_code;
     geis_error_count;
     geis_error_message;
     geis_get_configuration;
     geis_new;
+    geis_next_event;
+    geis_register_event_callback;
     geis_set_configuration;
     geis_subscription_add_filter;
     geis_subscription_delete;

=== modified file 'testsuite/libutouch-geis/Makefile.am'
--- testsuite/libutouch-geis/Makefile.am	2010-12-02 16:54:02 +0000
+++ testsuite/libutouch-geis/Makefile.am	2010-12-13 14:34:12 +0000
@@ -32,8 +32,10 @@
 
 check_geis2_internals_SOURCES = \
 	check_attr.c \
+	check_backend_event_posting.c \
 	check_backend_multiplexor.c \
 	check_error_reporting.c \
+	check_event_queue.c \
 	check_subscription.c \
 	check_geis2_internals.c
 

=== modified file 'testsuite/libutouch-geis/check_attr.c'
--- testsuite/libutouch-geis/check_attr.c	2010-11-26 18:22:53 +0000
+++ testsuite/libutouch-geis/check_attr.c	2010-12-13 14:34:12 +0000
@@ -48,6 +48,31 @@
 END_TEST
 
 
+/* verify bag get operation (positive results) */
+START_TEST(get_success)
+{
+  GeisAttr dst_attr;
+  GeisAttr src_attr = geis_attr_new("test-attr",
+                                    GEIS_ATTR_TYPE_STRING,
+                                    (void*)test_attr_string);
+  geis_attr_bag_insert(g_attr_bag, src_attr);
+  dst_attr = geis_attr_bag_attr(g_attr_bag, 0);
+  fail_if(dst_attr == NULL, "expected instance not found");
+  fail_unless(0 == strcmp(geis_attr_value_to_string(dst_attr), test_attr_string),
+              "unexpected attribute value returned");
+}
+END_TEST
+
+
+/* verify bag get operation (negative results) */
+START_TEST(get_fail)
+{
+  GeisAttr attr = geis_attr_bag_attr(g_attr_bag, 5);
+  fail_unless(attr == NULL, "unexpected instance indexed");
+}
+END_TEST
+
+
 /* verify bag find operation (positive results) */
 START_TEST(find_success)
 {
@@ -86,6 +111,8 @@
   TCase *usage = tcase_create("attr-bag-usage");
   tcase_add_checked_fixture(usage, construct_bag, destroy_bag);
   tcase_add_test(usage, insertion);
+  tcase_add_test(usage, get_success);
+  tcase_add_test(usage, get_fail);
   tcase_add_test(usage, find_success);
   tcase_add_test(usage, find_fail);
   suite_add_tcase(s, usage);

=== added file 'testsuite/libutouch-geis/check_backend_event_posting.c'
--- testsuite/libutouch-geis/check_backend_event_posting.c	1970-01-01 00:00:00 +0000
+++ testsuite/libutouch-geis/check_backend_event_posting.c	2010-12-13 14:34:12 +0000
@@ -0,0 +1,70 @@
+/**
+ * internal unit test for the back end event posting interface
+ */
+#include <check.h>
+
+#include "geis/geis.h"
+#include "libutouch-geis/geis_event.h"
+#include "libutouch-geis/geis_private.h"
+
+/* fixtures */
+Geis g_geis;
+
+static void
+construct_geis()
+{
+  g_geis = geis_new(GEIS_INIT_UTOUCH_MOCK_ENGINE, NULL);
+}
+
+static void
+destroy_geis()
+{
+  geis_delete(g_geis);
+}
+
+START_TEST(backend_post)
+{
+  GeisStatus status;
+  GeisEvent event_in = geis_event_new(GEIS_EVENT_TYPE_GESTURE_END);
+  GeisEvent event_out;
+
+  geis_post_event(g_geis, event_in);
+  status = geis_dispatch_events(g_geis);
+  fail_unless(status == GEIS_STATUS_SUCCESS,
+              "unexpected status from geis_dispatch_events");
+  status = geis_next_event(g_geis, &event_out);
+  fail_unless(status == GEIS_STATUS_SUCCESS,
+              "unexpected status from geis_next_event");
+  fail_unless(geis_event_type(event_in) == geis_event_type(event_out),
+              "event in and event out types do not match");
+
+  geis_post_event(g_geis, event_in);
+  geis_post_event(g_geis, event_in);
+  status = geis_dispatch_events(g_geis);
+  fail_unless(status == GEIS_STATUS_SUCCESS,
+              "unexpected status from geis_dispatch_events");
+  status = geis_next_event(g_geis, &event_out);
+  fail_unless(status == GEIS_STATUS_CONTINUE,
+              "expected CONTINUE status from geis_next_event");
+  status = geis_next_event(g_geis, &event_out);
+  fail_unless(status == GEIS_STATUS_SUCCESS,
+              "expected SUCCESS status from geis_next_event");
+
+  geis_event_delete(event_in);
+}
+END_TEST
+
+/* boilerplate */
+Suite *
+make_backend_event_posting_suite()
+{
+  Suite *s = suite_create("utouch-geis2-backend-event-posting");
+
+  TCase *usage = tcase_create("backend-event-posting-usage");
+  tcase_add_checked_fixture(usage, construct_geis, destroy_geis);
+  tcase_add_test(usage, backend_post);
+  suite_add_tcase(s, usage);
+
+  return s;
+}
+

=== added file 'testsuite/libutouch-geis/check_event_queue.c'
--- testsuite/libutouch-geis/check_event_queue.c	1970-01-01 00:00:00 +0000
+++ testsuite/libutouch-geis/check_event_queue.c	2010-12-13 14:34:12 +0000
@@ -0,0 +1,88 @@
+/**
+ * unit tests for the geis_event_queue module
+ */
+#include <check.h>
+
+#include "geis/geis.h"
+#include "libutouch-geis/geis_event.h"
+#include "libutouch-geis/geis_event_queue.h"
+
+
+/* fixtures */
+static GeisEventQueue g_queue;
+
+/* fixture setup */
+static void
+construct_event_queue()
+{
+  g_queue = geis_event_queue_new();
+}
+
+/* fixture teardown */
+static void
+destroy_event_queue()
+{
+  geis_event_queue_delete(g_queue);
+}
+
+
+/* verify event queue construction/destruction */
+START_TEST(construction)
+{
+  construct_event_queue();
+  fail_unless(g_queue != NULL, "failed to create the event queue");
+  fail_unless(geis_event_queue_is_empty(g_queue), "queue is not empty");
+  destroy_event_queue();
+}
+END_TEST
+
+
+/* verify event_queue insertion */
+START_TEST(enqueue_dequeue)
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  GeisEvent event1 = geis_event_new(GEIS_EVENT_TYPE_GESTURE_BEGIN);
+  GeisEvent event2 = geis_event_new(GEIS_EVENT_TYPE_GESTURE_END);
+  GeisEvent ev;
+
+  ev = geis_event_queue_dequeue(g_queue);
+  fail_unless(ev == NULL, "unexpected failure at pop(0)");
+
+  status = geis_event_queue_enqueue(g_queue, event1);
+  fail_unless(status == GEIS_STATUS_SUCCESS, "failure at enqueue(event1)");
+  fail_unless(!geis_event_queue_is_empty(g_queue), "queue is unexpectedly empty");
+  status = geis_event_queue_enqueue(g_queue, event2);
+  fail_unless(status == GEIS_STATUS_SUCCESS, "failure at enqueue(event2)");
+
+  ev = geis_event_queue_dequeue(g_queue);
+  fail_unless(ev != NULL, "failure at dequeue(1)");
+  fail_unless(ev == event1, "unexpected value returned from front(1)");
+
+  ev = geis_event_queue_dequeue(g_queue);
+  fail_unless(ev != NULL, "failure at dequeue(2)");
+  fail_unless(ev == event2, "unexpected value returned from front(2)");
+
+  ev = geis_event_queue_dequeue(g_queue);
+  fail_unless(ev == NULL, "failure at dequeue(3)");
+  fail_unless(geis_event_queue_is_empty(g_queue), "queue is not empty");
+}
+END_TEST
+
+/* boilerplate */
+Suite *
+make_event_queue_suite()
+{
+  Suite *s = suite_create("utouch-geis2-event-queue");
+
+  TCase *create = tcase_create("event-queue-creation");
+  tcase_add_test(create, construction);
+  suite_add_tcase(s, create);
+
+  TCase *usage = tcase_create("event-queue-operation");
+  tcase_add_checked_fixture(usage, construct_event_queue, destroy_event_queue);
+  tcase_add_test(usage, enqueue_dequeue);
+  suite_add_tcase(s, usage);
+
+  return s;
+}
+

=== modified file 'testsuite/libutouch-geis/check_geis2_internals.c'
--- testsuite/libutouch-geis/check_geis2_internals.c	2010-12-02 16:54:02 +0000
+++ testsuite/libutouch-geis/check_geis2_internals.c	2010-12-13 14:34:12 +0000
@@ -3,10 +3,14 @@
  */
 #include <check.h>
 
+#define LOGFILE_PREFIX "geis2_internals"
+
+extern Suite *make_attr_suite();
+extern Suite *make_backend_event_posting_suite();
+extern Suite *make_backend_multiplexor_suite();
 extern Suite *make_error_reporting_suite();
-extern Suite *make_attr_suite();
+extern Suite *make_event_queue_suite();
 extern Suite *make_subscription_suite();
-extern Suite *make_backend_multiplexor_suite();
 
 
 int
@@ -19,10 +23,13 @@
   SRunner *sr = srunner_create(s);
   srunner_add_suite(sr, make_error_reporting_suite());
   srunner_add_suite(sr, make_attr_suite());
+  srunner_add_suite(sr, make_event_queue_suite());
+  srunner_add_suite(sr, make_backend_multiplexor_suite());
+  srunner_add_suite(sr, make_backend_event_posting_suite());
   srunner_add_suite(sr, make_subscription_suite());
-  srunner_add_suite(sr, make_backend_multiplexor_suite());
 
-  srunner_set_log(sr, "geis2_internals.log");
+  srunner_set_log(sr, LOGFILE_PREFIX".log");
+  srunner_set_xml(sr, LOGFILE_PREFIX".xml");
   srunner_run_all(sr, CK_NORMAL);
   num_failed = srunner_ntests_failed(sr);