Bugs

You can submit bug reports at http://bugs.dronelabs.com/.

Catalina API documentation can be found http://docs.dronelabs.com/catalina/api

Introduction

Catalina is a data store for applications that use GLib/GObject. It can transparently serialize data in a cross-endian way including ints, strings, doubles, and objects. Along with serialization, Catalina also supports compression to and from storage. Currently, Berkeley DB is used for the persistant storage, but this may change in the future to a data-store that is commercial-license friendly.

Features

Key/Value storage with string or buffer-based keys
Simple and clean API
Serialization of GValue's using CatalinaFormatter
A binary serializer of CatalinaFormatter; Provides a tight, cross-endian data format
Data transformations to and from storage
Transparent compression possible using CatalinaZlibTransform
Optimized for asynchronous access, synchronous also available
Watermark for compression to only compress buffers larger than "watermark bytes" in length.

Future Goals

Alternate indexes for faster access based on user-provided values
Object versioning for CatalinaBinaryFormatter to handle translating between a different version of GObject in storage compared to runtime. A good example of this is when a new version of an application changes the properties/members of an object and some data becomes invalid or new data was added.

Installation

Compiling from Source

You can compile Catalina in the standard way for open-source projects on Linux. If you have a non-standard Berkeley DB installation, you can use the --with-bdb-dir= option. Catalina currently requires BDB, glib-2.0 >= 2.16 and iris-1.0 > 0.1.1.

Iris can be retrieved from http://git.dronelabs.com/iris.

  $ git clone git://git.dronelabs.com/catalina
  $ cd catalina
  $ ./autogen.sh --prefix=/usr
  $ make
  $ sudo make install

Ubuntu Linux

Ubuntu has a much faster installation method. You may add Christian's PPA and install all the dependencies with apt-get.

  # cat <<EOF >> /etc/apt/sources.list
  > deb http://ppa.launchpad.net/audidude/ppa/ubuntu jaunty main
  > deb-src http://ppa.launchpad.net/audidude/ppa/ubuntu jaunty main
  > EOF
  # apt-get update
  # apt-get install libcatalina-dev libcatalina-doc

Examples

Asynchronous

1 #include <stdlib.h>
2 #include <catalina/catalina.h>
3 #include <iris/iris.h>
4
5 static void
6 set_value_cb (GObject       *object,
7               GAsyncResult  *result,
8               gpointer       user_data)
9 {
10         CatalinaStorage *storage   = CATALINA_STORAGE (object);
11         GMainLoop       *main_loop = user_data;
12         GError          *error     = NULL;
13
14         if (!catalina_storage_set_value_finish (storage, result, &error))
15                 g_printerr ("%s: %s\n", __func__, error->message);
16         else
17                 g_print ("%s: value stored successfully!\n", __func__);
18
19         g_main_loop_quit (main_loop);
20 }
21
22 static void
23 open_cb (GObject       *object,
24          GAsyncResult  *result,
25          gpointer       user_data)
26 {
27         CatalinaStorage *storage   = CATALINA_STORAGE (object);
28         GMainLoop       *main_loop = user_data;
29         GError          *error     = NULL;
30         GValue           answer    = {0,};
31
32         if (!catalina_storage_open_finish (storage, result, &error)) {
33                 g_printerr ("%s: %s\n", __func__, error->message);
34                 g_main_loop_quit (main_loop);
35                 return;
36         }
37
38         g_value_init (&answer, G_TYPE_INT);
39         g_value_set_int (&answer, 42);
40         catalina_storage_set_value_async (storage,
41                                           "the-answer", -1, /* key & key_length   */
42                                           &answer,          /* value to serialize */
43                                           set_value_cb,
44                                           main_loop);
45 }
46
47 gint
48 main (gint   argc,
49       gchar *argv[])
50 {
51         GMainLoop       *main_loop;
52         CatalinaStorage *storage;
53
54         g_type_init ();
55         iris_init ();
56
57         /* create main loop */
58         main_loop = g_main_loop_new (NULL, FALSE);
59
60         /* create storage */
61         storage = catalina_storage_new ();
62
63         /* support serialization and and compress data on disk */
64         g_object_set (storage,
65                       "formatter", catalina_binary_formatter_new (),
66                       "transform", catalina_zlib_transform_new (),
67                       NULL);
68
69         /* open the database asynchronously */
70         catalina_storage_open_async (storage,
71                                      ".",          /* env dir */
72                                      "storage.db", /* db name */
73                                      open_cb,
74                                      main_loop);
75
76         /* run the main loop until the example finishes */
77         g_main_loop_run (main_loop);
78
79         return EXIT_SUCCESS;
80 }

Synchronous

There is a synchronous API, however it is not going to be as fast as the asynchronous API. It uses GMutex and GCond to signal back and forth between the storage threads and the caller thread.

1 #include <stdlib.h>
2 #include <catalina/catalina.h>
3 #include <iris/iris.h>
4
5 gint
6 main (gint   argc,
7       gchar *argv[])
8 {
9         CatalinaStorage *storage;
10         GError          *error = NULL;
11         GValue           value = {0,};
12
13         g_type_init ();
14         iris_init ();
15
16         /* create storage */
17         storage = catalina_storage_new ();
18
19         /* support serialization and and compress data on disk */
20         g_object_set (storage,
21                       "formatter", catalina_binary_formatter_new (),
22                       "transform", catalina_zlib_transform_new (),
23                       NULL);
24
25         /* open the database synchronously */
26         if (!catalina_storage_open (storage,
27                                     ".",          /* env dir */
28                                     "storage.db", /* db name */
29                                     &error))
30                 g_error ("%s", error->message);
31
32         g_value_init (&value, G_TYPE_STRING);
33         g_value_set_string (&value, "This is some random string that gets serialized and "
34                                     "compressed before written to disk.");
35
36         /* store the value synchronously */
37         if (!catalina_storage_set_value (storage,
38                                          "some-key", -1, /* key, key-length    */
39                                          &value,         /* value to serialize */
40                                          &error))
41                 g_error ("%s", error->message);
42
43         g_print ("%s: serialized and stored value to storage\n", __func__);
44
45         /* synchronously close the storage */
46         catalina_storage_close (storage, NULL);
47
48         return EXIT_SUCCESS;
49 }

Licensing

Catalina is licensed under the LGPL-2. However, Berkeley DB has dual licensing which requires applications linking against it to be open-source or pay for a commercial license. Therfore, the underlying storage will change from Berkeley DB in the very near future.

Authors

Christian Hergert <chris@dronelabs.com>