[glib/gobject-performance-2] Cleanup and add docs to GAtomicArray

[Alexander Larsson <alexl src gnome org>]

commit edd9ab4674eb4c1cc517c307327a9b8a44f641d8
Author: Alexander Larsson <alexl redhat com>
Date:   Fri Nov 27 15:36:24 2009 +0100

    Cleanup and add docs to GAtomicArray

 gobject/gatomicarray.c |   24 ++++++++++++++++++++++--
 gobject/gatomicarray.h |    4 ++--
 2 files changed, 24 insertions(+), 4 deletions(-)
---
diff --git a/gobject/gatomicarray.c b/gobject/gatomicarray.c
index cc15d62..a5002ed 100644
--- a/gobject/gatomicarray.c
+++ b/gobject/gatomicarray.c
@@ -35,7 +35,7 @@
  * or not. Thus the reading transaction cannot for instance
  * dereference a pointer in the array inside the transaction.
  *
- * The size of an array does however cannot change during a read
+ * The size of an array however cannot change during a read
  * transaction.
  *
  * Writes to the array is done in a copy-update style, but there
@@ -51,7 +51,8 @@ struct _FreeListNode {
 };
 
 /* This is really a list of array memory blocks, using the
-   first item as the next pointer to chain them together. */
+ * first item as the next pointer to chain them together.
+ * Protected by array lock */
 static FreeListNode *freelist = NULL;
 
 /* must hold array lock */
@@ -98,6 +99,18 @@ g_atomic_array_init (GAtomicArray *array)
   array->data = NULL;
 }
 
+/* Get a copy of the data (if non-NULL) that
+ * can be changed and then re-applied with
+ * g_atomic_array_update().
+ *
+ * If additional_element_size is > 0 then
+ * then the new memory chunk is that much
+ * larger, or there were no data we return
+ * a chunk of header_size + additional_element_size.
+ * This means you can use this to grow the
+ * array part and it handles the first element
+ * being added automatically.
+ */
 gpointer
 g_atomic_array_copy (GAtomicArray *array,
 		     gsize header_size,
@@ -134,6 +147,10 @@ g_atomic_array_copy (GAtomicArray *array,
   return new;
 }
 
+/* Replace the data in the array with the new data,
+ * freeing the old data (for reuse). The new data may
+ * not be smaller than the current data.
+ */
 void
 g_atomic_array_update (GAtomicArray *array, gpointer new_data)
 {
@@ -141,6 +158,9 @@ g_atomic_array_update (GAtomicArray *array, gpointer new_data)
 
   G_LOCK (array);
   old = g_atomic_pointer_get (&array->data);
+
+  g_assert (old == NULL || G_ATOMIC_ARRAY_DATA_SIZE (old) <= G_ATOMIC_ARRAY_DATA_SIZE (new_data));
+
   g_atomic_pointer_set (&array->data, new_data);
   if (old)
     freelist_free (old);
diff --git a/gobject/gatomicarray.h b/gobject/gatomicarray.h
index 9584ed6..d9dfb53 100644
--- a/gobject/gatomicarray.h
+++ b/gobject/gatomicarray.h
@@ -47,11 +47,11 @@ void     g_atomic_array_update (GAtomicArray *array,
     gpointer *_datap  = &(_array)->data;					\
     _type *transaction_data, *__check;						\
 										\
-    __check = g_atomic_pointer_get (_datap);				\
+    __check = g_atomic_pointer_get (_datap);					\
     do {									\
       transaction_data = __check;						\
       {_C_;}									\
-      __check = g_atomic_pointer_get (_datap);				\
+      __check = g_atomic_pointer_get (_datap);					\
     } while (transaction_data != __check);					\
   } G_STMT_END