Merge lp:~oif-team/geis/geis2_add_regions into lp:geis

[Stephen M. Webb]

Added GEIS v2.0 region module with accompanying unit test suites.

[Henrik Rydberg (rydberg)]

//GeisRegion geis_region_new()
+ geis_error("error allocaring region");

+ while (init_arg_name)
+ {
+ if (0 == strcmp(init_arg_name, GEIS_REGION_X11_ROOT))
+ {
+ region->type = strdup(init_arg_name);
+ geis_debug("using X11 root");

a break here would make it more apparent that type is normally assigned once

+ }
+ else if (0 == strcmp(init_arg_name, GEIS_REGION_X11_WINDOWID))
+ {
+ region->type = strdup(init_arg_name);
+ region->data.windowid = va_arg(varargs, int);
+ geis_debug("using X11 windowid 0x%08x", region->data.windowid);

ditto

+ }

//GeisStatus geis_region_delete(GeisRegion region)
+{
+ --region->ref_count;
+ if (0 == region->ref_count)

With this construct, we will have to be careful when using threads operating under mutexes against a single geis instance. If two threads happen to queue for the same code path... boom.

Reading on, I see you already warn about this in the text.

A way around this is to split the ref counting from the actual freeing, and keep old regions around for recycling.

+ {
+ if (region->name)
+ free((char *)region->name);
+ free((char *)region->type);
+ free(region);
+ }
+ return GEIS_STATUS_SUCCESS;
+}

Thanks!

review: Needs Fixing

[lp:~oif-team/geis/geis2_add_regions]

96. By Stephen M. Webb on 2010-12-17

Added GEIS v2.0 region module.

[Stephen M. Webb (bregma)]

Fixed the comment typo, added the missing duplicate checks, and made the refcounting atomic to avoid threading issues. The container is still not threadsafe, that can come later.

[Henrik Rydberg (rydberg)]

Very nice! The "if (region->name)" is redundant, but never mind.

review: Approve

[Chase Douglas (chasedouglas)]

I know this has been merged, but I would like to see geis_region_delete() renamed to something like geis_region_deref() or geis_region_release(). Delete implies that the object will be freed immediately, which is not what happens here if a reference is held elsewhere.

[Stephen M. Webb (bregma)]

On Tue, 2010-12-21 at 18:28 +0000, Chase Douglas wrote:
> I know this has been merged, but I would like to see geis_region_delete() renamed to something
> like geis_region_deref() or geis_region_release(). Delete implies that the object will be freed
> immediately, which is not what happens here if a reference is held elsewhere.

That would be awfully confusing for the library user, considering there
is no geis_region_ref() anywhere in sight. In fact, the library user
has no idea this is a reference counted object. As far as they are
concerned, when they call geis_region_delete(), the object is deleted
and is no longer valid.

The refcounting is an internal feature of this particular object to
ensure persistence event though lifetime control is in the user's hands.
The refcounting is explicit on other objects because they are created by
the API rather than the user.

The rest of the library uses _new() and _delete() as the construction
and destruction calls where object lifetime is under the control of the
user. Consistency in an API is a good thing.

I'm less worried about what has to go on under the hood to make things
easier for the library user, since I'm assuming anyone who is
maintaining the library is capable of figuring things out by reading the
code. The typical library user should not have to read the code.

--
Stephen M. Webb <email address hidden>
Canonical Ltd.

[Chase Douglas (chasedouglas)]

Ahh, I thought the _ref() function was public. I'm fine with it as is then.

=== modified file 'ChangeLog'
--- ChangeLog	2010-12-15 01:48:35 +0000
+++ ChangeLog	2010-12-17 02:59:09 +0000
@@ -1,3 +1,24 @@
[phone]  Stephen M. Webb  <[e-mail]>
+
+  Added GEIS v2.0 region module.
+
+  * libutouch-geis/geis_region.c: new file
+  * libutouch-geis/geis_region.h: new file
+  * testsuite/geis2/check_region.c: new test suite
+  * testsuite/libutouch-geis/check_region.c: new test suite
+  * include/geis/geis.h (GeisRegion): new typedef
+    (GEIS_REGION_X11_ROOT): new region initialization constant
+    (GEIS_REGION_X11_WINDOWID): new region initialization constant
+    (geis_region_new): new function
+    (geis_region_delete): new function
+    (geis_region_name): new function
+  * libutouch-geis/Makefile.am: added new files
+  * libutouch-geis/libutouch-geis.ver: added new symbols
+  * testsuite/geis2/Makefile.am: added new test suite files
+  * testsuite/geis2/check_geis2_api.c: added new test suite 
+  * testsuite/libutouch-geis/Makefile.am: added new test suite files
+  * testsuite/libutouch-geis/check_geis2_internals.c: added new test suite
+
 2010-12-12  Stephen M. Webb  <[e-mail]>
 
   Fixed some container expansion errors.
 
=== modified file 'include/geis/geis.h'
--- include/geis/geis.h	2010-12-15 01:48:35 +0000
+++ include/geis/geis.h	2010-12-17 02:59:09 +0000
@@ -636,6 +636,64 @@
 /* @} */
 
 /**
+ * @defgroup geis2_region Gesture Regions (GEIS v2.0)
+ * @{
+ */
+
+typedef struct _GeisRegion *GeisRegion;
+
+/**
+ * @defgroup geis2_region_init_args Gesture Region Initialization Arguments
+ *
+ * Gesture regions are created to describe a particular display/feedback region.
+ * The type of the region can not be changed after creation (just create a new
+ * region for that).  The types of regions are platform specific and each type
+ * may require addition arguments.
+ *
+ * The following region initialization argument names are required by the
+ * GEIS v2.0 specification.
+ *
+ * @{
+ */
+#define GEIS_REGION_X11_ROOT       "org.libgeis.region.x11.root"
+#define GEIS_REGION_X11_WINDOWID   "org.libgeis.region.x11.windowid"
+
+/* @} */
+
+/**
+ * Creates a new GEIS v2.0 region.
+ *
+ * @param[in] geis           The GEIS API instance.
+ * @param[in] name           A name.  Used for diagnostics.
+ * @param[in] init_arg_name  The name of the first initialization argument.
+ *
+ * The initialization argument list must be terminated by a NULL.
+ *
+ * @returns a newly created region, or NULL on failure.
+ */
+GEIS_API GeisRegion geis_region_new(Geis       geis,
+                                    GeisString name,
+                                    GeisString init_arg_name, ...);
+
+/**
+ * Destroys a GEIS v2.0 region.
+ *
+ * @param[in] region  The region.
+ */
+GEIS_API GeisStatus geis_region_delete(GeisRegion region);
+
+/**
+ * Gets the name of a GEIS v2.0 region.
+ *
+ * @param[in] region  The region.
+ *
+ * Returns the @p name value used when creating the region.
+ */
+GEIS_API GeisString geis_region_name(GeisRegion region);
+
+/* @} */
+
+/**
  * @defgroup geis2_subscription Gesture Subscription (GEIS v2.0)
  * @{
  */
 
=== modified file 'libutouch-geis/Makefile.am'
--- libutouch-geis/Makefile.am	2010-12-09 16:14:15 +0000
+++ libutouch-geis/Makefile.am	2010-12-17 02:59:09 +0000
@@ -32,6 +32,7 @@
 	geis_event.h                geis_event.c \
 	geis_event_queue.h          geis_event_queue.c \
 	geis_logging.h              geis_logging.c \
+	geis_region.h               geis_region.c \
 	geis_subscription.h         geis_subscription.c \
 	geis_private.h              geis.c
 
 
=== added file 'libutouch-geis/geis_region.c'
--- libutouch-geis/geis_region.c	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_region.c	2010-12-17 02:59:09 +0000
@@ -0,0 +1,291 @@
+/**
+ * @file libutouch-geis/geis_region.c
+ * @brief implementation of the uTouch GEIS v2.0 API region 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
+ */
+#include "geis_config.h"
+#include "geis_region.h"
+
+#include "geis_error.h"
+#include "geis_logging.h"
+#include <string.h>
+#include <stdarg.h>
+#include <stdlib.h>
+
+
+struct _GeisRegion
+{
+  int         ref_count;
+  GeisString  type;
+  GeisString  name;
+  union {
+    int windowid;
+  } data;
+};
+
+struct _GeisRegionBag
+{
+  GeisRegion *region_store;
+  GeisSize    region_store_size;
+  GeisSize    region_count;
+};
+
+static const int region_bag_growth_constant = 2;
+
+
+/*
+ * Constructs a region bag.
+ */
+GeisRegionBag
+geis_region_bag_new()
+{
+  GeisRegionBag bag = calloc(1, sizeof(struct _GeisRegionBag));
+  if (!bag)
+  {
+    geis_error("failed to allocate region bag");
+    goto final_exit;
+  }
+
+  bag->region_store_size = 3;
+  bag->region_count = 0;
+  bag->region_store = calloc(bag->region_store_size, sizeof(GeisRegion));
+  if (!bag->region_store)
+  {
+    geis_error("failed to allocate region bag store");
+    goto unwind_bag;
+  }
+  goto final_exit;
+
+unwind_bag:
+  free(bag);
+final_exit:
+  return bag;
+}
+
+
+/*
+ * Destroys a region bag.
+ */
+void
+geis_region_bag_delete(GeisRegionBag bag)
+{
+  GeisSize i;
+  for (i = bag->region_count; i > 0; --i)
+  {
+    geis_region_delete(bag->region_store[i-1]);
+  }
+  free(bag);
+}
+
+
+/*
+ * Gets the number of regions held in a bag.
+ */
+GeisSize
+geis_region_bag_count(GeisRegionBag bag)
+{
+  return bag->region_count;
+}
+
+
+/*
+ * Gets an indicated region from a bag.
+ */
+GeisRegion
+geis_region_bag_region(GeisRegionBag bag, GeisSize index)
+{
+  GeisRegion region = NULL;
+  if (index < bag->region_count)
+  {
+    region = bag->region_store[index];
+  }
+  return region;
+}
+
+
+/*
+ * Puts a region into a bag.
+ */
+GeisStatus
+geis_region_bag_insert(GeisRegionBag bag, GeisRegion region)
+{
+  GeisStatus status = GEIS_STATUS_UNKNOWN_ERROR;
+  if (bag->region_count >= bag->region_store_size)
+  {
+    GeisSize new_store_size = bag->region_store_size * region_bag_growth_constant;
+    GeisRegion *new_store = realloc(bag->region_store,
+             new_store_size * sizeof(struct _GeisRegion));
+    if (!new_store)
+    {
+      geis_error("failed to reallocate region bag");
+      goto error_exit;
+    }
+    bag->region_store = new_store;
+    bag->region_store_size = new_store_size;
+  }
+  bag->region_store[bag->region_count++] = region;
+  status = GEIS_STATUS_SUCCESS;
+
+error_exit:
+  return status;
+}
+
+
+/**
+ * Takes a region out of a bag.
+ */
+GeisStatus
+geis_region_bag_remove(GeisRegionBag bag, GeisRegion region)
+{
+  GeisSize i;
+  GeisStatus status = GEIS_STATUS_SUCCESS;
+  for (i = 0; i < bag->region_count; ++i)
+  {
+    if (bag->region_store[i] == region)
+    {
+      GeisSize j;
+      geis_region_delete(bag->region_store[i]);
+      --bag->region_count;
+      for (j = i; j < bag->region_count; ++j)
+      {
+	bag->region_store[j] = bag->region_store[j+1];
+      }
+      break;
+    }
+  }
+  return status;
+}
+
+
+/*
+ * Constructs a region.
+ */
+GeisRegion
+geis_region_new(Geis       geis,
+                GeisString name,
+                GeisString init_arg_name, ...)
+{
+  GeisRegion region = NULL;
+  va_list    varargs;
+
+  region = calloc(1, sizeof(struct _GeisRegion));
+  if (!region)
+  {
+    geis_error_push(geis, GEIS_STATUS_UNKNOWN_ERROR);
+    geis_error("error allocating region");
+    goto final_exit;
+  }
+
+  va_start(varargs, init_arg_name);
+  while (init_arg_name)
+  {
+    if (0 == strcmp(init_arg_name, GEIS_REGION_X11_ROOT))
+    {
+      if (region->type)
+      {
+	geis_warning("multiple region types requested, only using the first");
+	break;
+      }
+      region->type = strdup(init_arg_name);
+      geis_debug("using X11 root");
+    }
+    else if (0 == strcmp(init_arg_name, GEIS_REGION_X11_WINDOWID))
+    {
+      if (region->type)
+      {
+	geis_warning("multiple region types requested, only using the first");
+	break;
+      }
+      region->type = strdup(init_arg_name);
+      region->data.windowid = va_arg(varargs, int);
+      geis_debug("using X11 windowid 0x%08x", region->data.windowid);
+    }
+
+    init_arg_name = va_arg(varargs, GeisString);
+  }
+  va_end(varargs);
+
+  ++region->ref_count;
+  region->name = strdup(name);
+
+final_exit:
+  return region;
+}
+
+
+/*
+ * Destroys a GEIS v2.0 region.
+ */
+GeisStatus
+geis_region_delete(GeisRegion region)
+{
+  if (0 == __sync_sub_and_fetch(&region->ref_count, 1))
+  {
+    if (region->name)
+      free((char *)region->name);
+    free((char *)region->type);
+    free(region);
+  }
+  return GEIS_STATUS_SUCCESS;
+}
+
+
+/**
+ * Gets the name of a GEIS v2.0 region.
+ *
+ * @param[in] region  The region.
+ *
+ * Returns the @p name value used when creating the region.
+ */
+GeisString
+geis_region_name(GeisRegion region)
+{
+  return region->name;
+}
+
+
+/*
+ * Adds a reference to a region.
+ */
+void
+geis_region_ref(GeisRegion region)
+{
+  __sync_add_and_fetch(&region->ref_count, 1);
+}
+
+
+/*
+ * Gets the type of the region.
+ */
+GeisString
+geis_region_type(GeisRegion region)
+{
+  return region->type;
+}
+
+
+/*
+ * Gets the data (if any) associated with the region type.
+ */
+void *
+geis_region_data(GeisRegion region)
+{
+  return &region->data;
+}
+
+
 
=== added file 'libutouch-geis/geis_region.h'
--- libutouch-geis/geis_region.h	1970-01-01 00:00:00 +0000
+++ libutouch-geis/geis_region.h	2010-12-17 02:59:09 +0000
@@ -0,0 +1,103 @@
+/**
+ * @file geis_region.h
+ * @brief internal uTouch Geis region module private 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_REGION_H_
+#define GEIS_REGION_H_
+
+#include "geis/geis.h"
+
+/**
+ * @struct _GeisRegion
+ *
+ * This is a refcounted object:  using the internal function geis_region_ref()
+ * will increment the reference count on the object, and geis_region_delete()
+ * will decrement the reference count and destroy the object when the reference
+ * count is set to zero.
+ *
+ * If you are handed a GeisRegion and want to keep it around, you need to ref it
+ * and then delete it when you're done, otherwise it could disappear out from
+ * under you.
+ *
+ * Because GeisRegion lifetime is affected explicitly by application action
+ * (new and delete calls are under application control), the refcount mechanism
+ * has been made threadsafe.
+ */
+
+/**
+ * Contains regions in no particular order, with no duplicate checking.
+ *
+ * @note This container is not threadsafe.
+ */
+typedef struct _GeisRegionBag *GeisRegionBag;
+
+/**
+ * Creates a new region bag.
+ */
+GeisRegionBag geis_region_bag_new();
+
+/**
+ * Destroys a region bag.
+ *
+ * @param[in] bag  The region bag.
+ */
+void geis_region_bag_delete(GeisRegionBag bag);
+
+/**
+ * Gets the number of regions held in a bag.
+ */
+GeisSize geis_region_bag_count(GeisRegionBag bag);
+
+/**
+ * Gets an indicated region from a bag.
+ */
+GeisRegion geis_region_bag_region(GeisRegionBag bag, GeisSize index);
+
+/**
+ * Puts a region into a bag.
+ */
+GeisStatus geis_region_bag_insert(GeisRegionBag bag, GeisRegion region);
+
+/**
+ * Takes a region out of a bag.
+ */
+GeisStatus geis_region_bag_remove(GeisRegionBag bag, GeisRegion region);
+
+/**
+ * Adds a reference to a region.
+ *
+ * @param[in] region  A region.
+ */
+void geis_region_ref(GeisRegion);
+
+/**
+ * Gets the type of the region.
+ *
+ * @param[in] region  A region.
+ */
+GeisString geis_region_type(GeisRegion region);
+
+/**
+ * Gets the data (if any) associated with the region type.
+ *
+ * @param[in] region  A region.
+ */
+void *geis_region_data(GeisRegion region);
+
+#endif /* GEIS_REGION_H_ */
 
=== modified file 'libutouch-geis/libutouch-geis.ver'
--- libutouch-geis/libutouch-geis.ver	2010-12-15 01:48:35 +0000
+++ libutouch-geis/libutouch-geis.ver	2010-12-17 02:59:09 +0000
@@ -27,6 +27,9 @@
     geis_get_configuration;
     geis_new;
     geis_next_event;
+    geis_region_delete;
+    geis_region_name;
+    geis_region_new;
     geis_register_event_callback;
     geis_set_configuration;
     geis_subscription_activate;
 
=== modified file 'testsuite/geis2/Makefile.am'
--- testsuite/geis2/Makefile.am	2010-11-29 02:16:02 +0000
+++ testsuite/geis2/Makefile.am	2010-12-17 02:59:09 +0000
@@ -18,6 +18,7 @@
 	check_error_codes.c \
 	check_geis_new.c \
 	check_general_types.c \
+	check_region.c \
 	check_subscription.c \
 	check_version_macro.c \
 	check_geis2_api.c
 
=== modified file 'testsuite/geis2/check_geis2_api.c'
--- testsuite/geis2/check_geis2_api.c	2010-11-29 02:16:02 +0000
+++ testsuite/geis2/check_geis2_api.c	2010-12-17 02:59:09 +0000
@@ -9,6 +9,7 @@
 extern Suite *geis2_error_codes_suite_new();
 extern Suite *geis2_geis_new_suite_new();
 extern Suite *geis2_config_suite_new();
+extern Suite *geis2_region_suite_new();
 extern Suite *geis2_subscription_suite_new();
 
 int
@@ -24,6 +25,7 @@
   srunner_add_suite(sr, geis2_error_codes_suite_new());
   srunner_add_suite(sr, geis2_geis_new_suite_new());
   srunner_add_suite(sr, geis2_config_suite_new());
+  srunner_add_suite(sr, geis2_region_suite_new()); 
   srunner_add_suite(sr, geis2_subscription_suite_new()); 
 
   srunner_set_log(sr, "geis2_api.log");
 
=== added file 'testsuite/geis2/check_region.c'
--- testsuite/geis2/check_region.c	1970-01-01 00:00:00 +0000
+++ testsuite/geis2/check_region.c	2010-12-17 02:59:09 +0000
@@ -0,0 +1,65 @@
+/**
+ * Unit tests for GEIS v2.0 region module
+ */
+#include <check.h>
+
+#include <geis/geis.h>
+#include <string.h>
+
+
+/* fixtures */
+static Geis g_geis;
+
+/* fixture setup */
+static void
+construct_geis()
+{
+  g_geis = geis_new(GEIS_INIT_UTOUCH_MOCK_ENGINE, NULL);
+}
+
+/* fixture teardown */
+static void
+destroy_geis()
+{
+  geis_delete(g_geis);
+}
+
+
+/* compile-time test to ensure required types are defined */
+START_TEST(region_constants)
+{
+  GeisString ini;
+  ini = GEIS_REGION_X11_ROOT;
+  ini = GEIS_REGION_X11_WINDOWID;
+}
+END_TEST
+
+START_TEST(construction)
+{
+  GeisRegion sub = geis_region_new(g_geis, "name", GEIS_REGION_X11_ROOT, NULL);
+  fail_unless(sub != NULL,
+              "failed to create region");
+  fail_unless(0 == strcmp(geis_region_name(sub), "name"),
+              "unexpected region name returned");
+  geis_region_delete(sub);
+}
+END_TEST
+
+/* boilerplate */
+Suite *
+geis2_region_suite_new()
+{
+  Suite *s = suite_create("geis2_region");
+
+  TCase *create = tcase_create("region-constants");
+  tcase_add_test(create, region_constants);
+  suite_add_tcase(s, create);
+
+  TCase *usage = tcase_create("region-usage");
+  tcase_add_checked_fixture(usage, construct_geis, destroy_geis);
+  tcase_add_test(usage, construction);
+  suite_add_tcase(s, usage);
+
+  return s;
+}
+
 
=== modified file 'testsuite/libutouch-geis/Makefile.am'
--- testsuite/libutouch-geis/Makefile.am	2010-12-13 03:53:15 +0000
+++ testsuite/libutouch-geis/Makefile.am	2010-12-17 02:59:09 +0000
@@ -36,6 +36,7 @@
 	check_backend_multiplexor.c \
 	check_error_reporting.c \
 	check_event_queue.c \
+	check_region.c \
 	check_subscription.c \
 	check_geis2_internals.c
 
 
=== modified file 'testsuite/libutouch-geis/check_geis2_internals.c'
--- testsuite/libutouch-geis/check_geis2_internals.c	2010-12-09 16:14:15 +0000
+++ testsuite/libutouch-geis/check_geis2_internals.c	2010-12-17 02:59:09 +0000
@@ -10,6 +10,7 @@
 extern Suite *make_backend_multiplexor_suite();
 extern Suite *make_error_reporting_suite();
 extern Suite *make_event_queue_suite();
+extern Suite *make_region_suite();
 extern Suite *make_subscription_suite();
 
 
@@ -26,6 +27,7 @@
   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_region_suite());
   srunner_add_suite(sr, make_subscription_suite());
 
   srunner_set_log(sr, LOGFILE_PREFIX".log");
 
=== added file 'testsuite/libutouch-geis/check_region.c'
--- testsuite/libutouch-geis/check_region.c	1970-01-01 00:00:00 +0000
+++ testsuite/libutouch-geis/check_region.c	2010-12-17 02:59:09 +0000
@@ -0,0 +1,112 @@
+/**
+ * internal unit tests for the uTouch GEIS v2.0 region module
+ *
+ * Note the public API is checked through the geis2 testsuite.
+ */
+#include <check.h>
+
+#include "geis/geis.h"
+#include "libutouch-geis/geis_region.h"
+#include <stdio.h>
+
+
+/* fixtures */
+static Geis g_geis;
+static GeisRegionBag g_region_bag;
+static uint16_t g_sample_windowid = 0x11;
+
+/* fixture setup */
+static void
+construct_bag()
+{
+  g_geis = geis_new(GEIS_INIT_UTOUCH_MOCK_ENGINE, NULL);
+  g_region_bag = geis_region_bag_new(1);
+}
+
+/* fixture teardown */
+static void
+destroy_bag()
+{
+  geis_region_bag_delete(g_region_bag);
+  geis_delete(g_geis);
+}
+
+
+START_TEST(region_access)
+{
+  GeisRegion region;
+  region = geis_region_new(g_geis, "test01",
+                           GEIS_REGION_X11_WINDOWID, g_sample_windowid,
+                           NULL);
+  fail_unless(0 == strcmp(geis_region_type(region), GEIS_REGION_X11_WINDOWID),
+              "bad region type");
+  fail_unless(g_sample_windowid == *(int *)geis_region_data(region),
+              "bad region data");
+}
+END_TEST
+
+/* verify bag construction/destruction */
+START_TEST(bag_construction)
+{
+  GeisRegionBag bag = geis_region_bag_new();
+  fail_unless(bag != NULL,
+              "failed to create region bag");
+  fail_unless(geis_region_bag_count(bag) == 0,
+              "unexpected size");
+  geis_region_bag_delete(bag);
+}
+END_TEST
+
+
+/* verify bag insertion */
+START_TEST(bag_insertion)
+{
+  GeisRegion region;
+  region = geis_region_new(g_geis, "test02", GEIS_REGION_X11_ROOT, NULL);
+  geis_region_bag_insert(g_region_bag, region);
+  fail_unless(geis_region_bag_count(g_region_bag) == 1,
+           "unexpected bag size after insertion");
+}
+END_TEST
+
+
+START_TEST(bag_expansion)
+{
+  int i;
+  GeisRegion region;
+  for (i = 0; i < 24; ++i)
+  {
+    char name[32];
+    sprintf(name, "%04d", i);
+    region = geis_region_new(g_geis, name, GEIS_REGION_X11_ROOT, NULL);
+    geis_region_bag_insert(g_region_bag, region);
+    int size = geis_region_bag_count(g_region_bag);
+    fail_if((size - 1) != i, "expected region bag size %d, got %d", i, size);
+  }
+}
+END_TEST
+
+
+/* boilerplate */
+Suite *
+make_region_suite()
+{
+  Suite *s = suite_create("utouch-geis2-region");
+
+  TCase *create = tcase_create("region-access");
+  tcase_add_test(create, region_access);
+  suite_add_tcase(s, create);
+
+  TCase *bag_create = tcase_create("region-bag-creation");
+  tcase_add_test(bag_create, bag_construction);
+  suite_add_tcase(s, bag_create);
+
+  TCase *bag_usage = tcase_create("region-bag-usage");
+  tcase_add_checked_fixture(bag_usage, construct_bag, destroy_bag);
+  tcase_add_test(bag_usage, bag_insertion);
+  tcase_add_test(bag_usage, bag_expansion);
+  suite_add_tcase(s, bag_usage);
+
+  return s;
+}
+