Pluggable libheimbase interface for DBs and misc libheimbase enhancements

[Code reviewed by Love Hörnquist Åstrand <lha@kth.se>]

    Added heim_db_*() entry points for dealing with databases, and
    make krb5_aname_to_localname() use it.

    The following enhancements to libheimbase are included:

     - Add heim_data_t and heim_string_t "reference" variants to
       avoid memory copies of potentially large data/strings.

       See heim_data_ref_create() and heim_string_ref_create().

     - Added enhancements to heim_array_t to allow their use for
       queues and stacks, and to improve performance.  See
       heim_array_insert_value().

     - Added XPath-like accessors for heim_object_t.  See
       heim_path_get(), heim_path_copy(), heim_path_create(), and
       heim_path_delete().  These are used extensively in the DB
       framework's generic composition of ACID support and in the
       test_base program

     - Made libheimbase more consistent with Core Foundation naming
       conventions.  See heim_{dict, array}_{get, copy}_value() and
       heim_path_{get, copy}().

     - Added functionality to and fixed bugs in base/json.c:
        - heim_serialize();
        - depth limit for JSON parsing (for DoS protection);
        - pretty-printing;
        - JSON compliance (see below);
        - flag options for parsing and serializing; these are needed
          because of impedance mismatches between heim_object_t and
          JSON (e.g., heim_dict_t allows non-string keys, but JSON
          does not; heimbase supports binary data, while JSON does
          not).

     - Added heim_error_enomem().

     - Enhanced the test_base program to test new functionality and
       to use heim_path*() to better test JSON encoding.  This
       includes some fuzz testing of JSON parsing, and running the
       test under valgrind.

     - Started to add doxygen documentation for libheimbase (but doc
       build for libheimbase is still incomplete).

    Note that there's still some incomplete JSON support:

     - JSON string quoting is not fully implemented;

     - libheimbase lacks support for real numbers, while JSON has
       it -- otherwise libheimbase is a superset of JSON,
       specifically in that any heim_object_t can be a key for an
       associative array.

    The following DB backends are supported natively:

     - "sorted-text", a binary search of sorted (in C locale), flat
       text files;

     - "json", a backend that stores DB contents serialized as JSON
       (this is intended for configuration-like contents).

    The DB framework supports:

     - multiple key/value tables per-DB
     - ACID transactions

    The DB framework also natively implements ACID transactions for
    any DB backends that a) do not provide transactions natively, b)
    do provide lock/unlock/sync methods (even on Windows).  This
    includes autocommit of DB updates outside transactions.

    Future DB enhancements may include:

     - add backends for various DB types (BDB, CDB, MDB, ...);

     - make libhdb use heim_db_t;

     - add a command-line tool for interfacing to databases via
       libheimbase (e.g., to get/set/delete values, create/copy/
       backup DBs, inspect history, check integrity);

     - framework-level transaction logging (with redo and undo
       logging), for generic incremental replication;

     - framework-level DB integrity checking.

       We could store a MAC of the XOR of a hash function applied to
       {key, value} for every entry in the DB, then use this to check
       DB integrity incrementally during incremental replication, as
       well as for the whole DB.

base/array.c

@@ -42,6 +42,8 @@
 struct heim_array_data {
     size_t len;
     heim_object_t *val;
+    size_t allocated_len;
+    heim_object_t *allocated;
 };
 
 static void
@@ -51,7 +53,7 @@ array_dealloc(heim_object_t ptr)
     size_t n;
     for (n = 0; n < array->len; n++)
 	heim_release(array->val[n]);
-    free(array->val);
+    free(array->allocated);
 }
 
 struct heim_type_data array_object = {
@@ -79,6 +81,8 @@ heim_array_create(void)
     if (array == NULL)
 	return NULL;
 
+    array->allocated = NULL;
+    array->allocated_len = 0;
     array->val = NULL;
     array->len = 0;
 
@@ -110,16 +114,134 @@ int
 heim_array_append_value(heim_array_t array, heim_object_t object)
 {
     heim_object_t *ptr;
+    size_t leading = array->val - array->allocated; /* unused leading slots */
+    size_t trailing = array->allocated_len - array->len - leading;
+    size_t new_len;
 
-    ptr = realloc(array->val, (array->len + 1) * sizeof(array->val[0]));
+    if (trailing > 0) {
+	/* We have pre-allocated space; use it */
+	array->val[array->len++] = heim_retain(object);
+	return 0;
+    }
+
+    if (leading > (array->len + 1)) {
+	/*
+	 * We must have appending to, and deleting at index 0 from this
+	 * array a lot; don't want to grow forever!
+	 */
+	(void) memmove(&array->allocated[0], &array->val[0],
+		       array->len * sizeof(array->val[0]));
+	array->val = array->allocated;
+
+	/* We have pre-allocated space; use it */
+	array->val[array->len++] = heim_retain(object);
+	return 0;
+    }
+
+    /* Pre-allocate extra .5 times number of used slots */
+    new_len = leading + array->len + 1 + (array->len >> 1);
+    ptr = realloc(array->allocated, new_len * sizeof(array->val[0]));
     if (ptr == NULL)
 	return ENOMEM;
-    array->val = ptr;
+    array->allocated = ptr;
+    array->allocated_len = new_len;
+    array->val = &ptr[leading];
     array->val[array->len++] = heim_retain(object);
 
     return 0;
 }
 
+/*
+ * Internal function to insert at index 0, taking care to optimize the
+ * case where we're always inserting at index 0, particularly the case
+ * where we insert at index 0 and delete from the right end.
+ */
+static int
+heim_array_prepend_value(heim_array_t array, heim_object_t object)
+{
+    heim_object_t *ptr;
+    size_t leading = array->val - array->allocated; /* unused leading slots */
+    size_t trailing = array->allocated_len - array->len - leading;
+    size_t new_len;
+
+    if (leading > 0) {
+	/* We have pre-allocated space; use it */
+	array->val--;
+	array->val[0] = heim_retain(object);
+	array->len++;
+	return 0;
+    }
+    if (trailing > (array->len + 1)) {
+	/*
+	 * We must have prepending to, and deleting at index
+	 * array->len - 1 from this array a lot; don't want to grow
+	 * forever!
+	 */
+	(void) memmove(&array->allocated[array->len], &array->val[0],
+		       array->len * sizeof(array->val[0]));
+	array->val = &array->allocated[array->len];
+
+	/* We have pre-allocated space; use it */
+	array->val--;
+	array->val[0] = heim_retain(object);
+	array->len++;
+	return 0;
+    }
+    /* Pre-allocate extra .5 times number of used slots */
+    new_len = array->len + 1 + trailing + (array->len >> 1);
+    ptr = realloc(array->allocated, new_len * sizeof(array->val[0]));
+    if (ptr == NULL)
+	return ENOMEM;
+    (void) memmove(&ptr[1], &ptr[0], array->len * sizeof (array->val[0]));
+    array->allocated = ptr;
+    array->allocated_len = new_len;
+    array->val = &ptr[0];
+    array->val[0] = heim_retain(object);
+    array->len++;
+
+    return 0;
+}
+
+/**
+ * Insert an object at a given index in an array
+ *
+ * @param array array to add too
+ * @param idx index where to add element (-1 == append, -2 next to last, ...)
+ * @param object the object to add
+ *
+ * @return zero if added, errno otherwise
+ */
+
+int
+heim_array_insert_value(heim_array_t array, size_t idx, heim_object_t object)
+{
+    int ret;
+
+    if (idx == 0)
+	return heim_array_prepend_value(array, object);
+    else if (idx > array->len)
+	heim_abort("index too large");
+
+    /*
+     * We cheat: append this element then rotate elements around so we
+     * have this new element at the desired location, unless we're truly
+     * appending the new element.  This means reusing array growth in
+     * heim_array_append_value() instead of duplicating that here.
+     */
+    ret = heim_array_append_value(array, object);
+    if (ret != 0 || idx == (array->len - 1))
+	return ret;
+    /*
+     * Shift to the right by one all the elements after idx, then set
+     * [idx] to the new object.
+     */
+    (void) memmove(&array->val[idx + 1], &array->val[idx],
+	           (array->len - idx - 1) * sizeof(array->val[0]));
+    array->val[idx] = heim_retain(object);
+
+    return 0;
+}
+
 /**
  * Iterate over all objects in array
  *
@@ -153,6 +275,39 @@ heim_array_iterate(heim_array_t array, void (^fn)(heim_object_t))
 }
 #endif
 
+/**
+ * Iterate over all objects in array, backwards
+ *
+ * @param array array to iterate over
+ * @param ctx context passed to fn
+ * @param fn function to call on each object
+ */
+
+void
+heim_array_iterate_reverse_f(heim_array_t array, void *ctx, heim_array_iterator_f_t fn)
+{
+    size_t n;
+    for (n = array->len; n > 0; n--)
+	fn(array->val[n - 1], ctx);
+}
+
+#ifdef __BLOCKS__
+/**
+ * Iterate over all objects in array, backwards
+ *
+ * @param array array to iterate over
+ * @param fn block to call on each object
+ */
+
+void
+heim_array_iterate_reverse(heim_array_t array, void (^fn)(heim_object_t))
+{
+    size_t n;
+    for (n = array->len; n > 0; n--)
+	fn(array->val[n - 1]);
+}
+#endif
+
 /**
  * Get length of array
  *
@@ -168,7 +323,25 @@ heim_array_get_length(heim_array_t array)
 }
 
 /**
- * Copy value of array
+ * Get value of element at array index
+ *
+ * @param array array copy object from
+ * @param idx index of object, 0 based, must be smaller then
+ *        heim_array_get_length()
+ *
+ * @return a not-retained copy of the object
+ */
+
+heim_object_t
+heim_array_get_value(heim_array_t array, size_t idx)
+{
+    if (idx >= array->len)
+	heim_abort("index too large");
+    return array->val[idx];
+}
+
+/**
+ * Get value of element at array index
  *
  * @param array array copy object from
  * @param idx index of object, 0 based, must be smaller then
@@ -178,11 +351,30 @@ heim_array_get_length(heim_array_t array)
  */
 
 heim_object_t
-heim_array_get_value(heim_array_t array, size_t idx)
+heim_array_copy_value(heim_array_t array, size_t idx)
 {
     if (idx >= array->len)
 	heim_abort("index too large");
-    return array->val[idx];
+    return heim_retain(array->val[idx]);
+}
+
+/**
+ * Set value at array index
+ *
+ * @param array array copy object from
+ * @param idx index of object, 0 based, must be smaller then
+ *        heim_array_get_length()
+ * @param value value to set 
+ *
+ */
+
+void
+heim_array_set_value(heim_array_t array, size_t idx, heim_object_t value)
+{
+    if (idx >= array->len)
+	heim_abort("index too large");
+    heim_release(array->val[idx]);
+    array->val[idx] = heim_retain(value);
 }
 
 /**
@@ -202,9 +394,21 @@ heim_array_delete_value(heim_array_t array, size_t idx)
 
     array->len--;
 
-    if (idx < array->len)
-	memmove(&array->val[idx], &array->val[idx + 1],
-		(array->len - idx) * sizeof(array->val[0]));
+    /*
+     * Deleting the first or last elements is cheap, as we leave
+     * allocated space for opportunistic reuse later; no realloc(), no
+     * memmove().  All others require a memmove().
+     *
+     * If we ever need to optimize deletion of non-last/ non-first
+     * element we can use a tagged object type to signify "deleted
+     * value" so we can leave holes in the array, avoid memmove()s on
+     * delete, and opportunistically re-use those holes on insert.
+     */
+    if (idx == 0)
+	array->val++;
+    else if (idx < array->len)
+	(void) memmove(&array->val[idx], &array->val[idx + 1],
+		       (array->len - idx) * sizeof(array->val[0]));
 
     heim_release(obj);
 }