Structured comment added to unique IDs pool code and some memory leak correction.

[ulut.git] / ulut / ul_uniqid.c

diff --git a/ulut/ul_uniqid.c b/ulut/ul_uniqid.c
index 64ad4f9f0292e168e9177eda87836de51cadde4f..4b0e9f49d96b0030fceddf24f1e9e0728ee17a08 100644 (file)
--- a/ulut/ul_uniqid.c
+++ b/ulut/ul_uniqid.c
@@ -49,6 +49,16 @@ GAVL_FLES_INT_IMP(ul_uniqid_pool, ul_uniqid_pool_t, ul_uniqid_pool_item_t, ul_un
        items, node, range, ul_uniqid_pool_cmp_fnc, GAVL_FANY, , , )
 
 
+/**
+ * ul_uniqid_pool_init - Initialize Unique IDs Pool
+ * @pool:      the pointer to the unique IDs pool
+ * @first:     the start of the available numeric range
+ * @last:      the end of the available numeric range
+ *
+ * Return Value: The function returns -1 if the @first>@last or if there
+ *     is not enough memory to allocate item for initial range representation.
+ *     The zero value indicates successful initialization.
+ */
 int ul_uniqid_pool_init(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_t last)
 {
   ul_uniqid_pool_item_t *item;
@@ -71,6 +81,12 @@ int ul_uniqid_pool_init(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_t l
   return 0;
 }
 
+/**
+ * ul_uniqid_pool_done - Finalize Unique IDs Pool
+ * @pool:      the pointer to the unique IDs pool
+ *
+ * Return Value: The zero value indicates success.
+ */
 int ul_uniqid_pool_done(ul_uniqid_pool_t *pool)
 {
   ul_uniqid_pool_item_t *item;
@@ -82,6 +98,20 @@ int ul_uniqid_pool_done(ul_uniqid_pool_t *pool)
   return 0;
 }
 
+/**
+ * ul_uniqid_pool_reserve - Reserve Range from the Unique IDs Pool
+ * @pool:      the pointer to the unique IDs pool
+ * @first:     the start value of the range
+ * @last:      the end value of the range
+ *
+ * The function checks if specified range @first..@last is free
+ * and reserves it from free pool.
+ *
+ * Return Value: The zero value indicates success. The value of -1 indicates,
+ *     that range overlaps with already reserved values or exceeds pool boundaries.
+ *     The value 1 is returned in the case, that there is not enough free memory
+ *     to represent new non-continuous ranges.
+ */
 int ul_uniqid_pool_reserve(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_t last)
 {
   ul_uniqid_range_t range;
@@ -107,6 +137,7 @@ int ul_uniqid_pool_reserve(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_
   if(range.first==item->range.first){
     if(range.last==item->range.last){
       ul_uniqid_pool_delete(pool, item);
+      free(item);
     }else{
       item->range.first=range.last+1;
     }
@@ -127,6 +158,18 @@ int ul_uniqid_pool_reserve(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_
 }
 
 
+/**
+ * ul_uniqid_pool_release - Release Range Back to the Unique IDs Pool
+ * @pool:      the pointer to the unique IDs pool
+ * @first:     the start value of the range
+ * @last:      the end value of the range
+ *
+ * The range @first..@last is returned to the pool for subsequent reuse.
+ *
+ * Return Value: The zero value indicates success. The value of -1 indicates,
+ *     that range cannot be return back, because there is no free memory
+ *     to allocate space for returned range.
+ */
 int ul_uniqid_pool_release(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_t last)
 {
   ul_uniqid_pool_item_t *post, *prev;
@@ -153,6 +196,7 @@ int ul_uniqid_pool_release(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_
       if(post){
         post->range.first=prev->range.first;
         ul_uniqid_pool_delete(pool, prev);
+        free(prev);
       }else{
         prev->range.last=range.last;
       }
@@ -169,6 +213,18 @@ int ul_uniqid_pool_release(ul_uniqid_pool_t *pool, ul_uniqid_t first, ul_uniqid_
   return 0;
 }
 
+/**
+ * ul_uniqid_pool_alloc_one - Allocate/Generate One Unique ID from the Pool
+ * @pool:      the pointer to the unique IDs pool
+ * @ptrid:     pointer to ul_uniqid_t variable where unique ID is returned
+ *
+ * The function allocates lowest available ID from the pool and assigns
+ * its value to the space pointed by @ptrid.
+ *
+ * Return Value: The zero value indicates success. The value of -1 indicates,
+ *     that all IDs from the pool are taken. No other reason is possible,
+ *     because function does not call any memory allocation function.
+ */
 int ul_uniqid_pool_alloc_one(ul_uniqid_pool_t *pool, ul_uniqid_t *ptrid)
 {
   ul_uniqid_t id;
@@ -181,12 +237,28 @@ int ul_uniqid_pool_alloc_one(ul_uniqid_pool_t *pool, ul_uniqid_t *ptrid)
     item->range.first=id+1;
   }else{
     ul_uniqid_pool_delete(pool, item);
+    free(item);
   }
   *ptrid=id;
   
   return 0;
 }
 
+/**
+ * ul_uniqid_pool_alloc_one_after - Allocate One Unique ID Greater Than Value Specified
+ * @pool:      the pointer to the unique IDs pool
+ * @ptrid:     pointer to ul_uniqid_t variable where unique ID is returned
+ * @afterid:   the ID value after which free ID is searched
+ *
+ * The function allocates the first available ID after @afterid from the
+ * pool and assigns its value to the space pointed by @ptrid.
+ * If there is no available ID with value greater than @afterid, the first free ID
+ * from the whole pool is returned.
+ *
+ * Return Value: The zero value indicates success. The value of -1 indicates,
+ *     that all IDs from the pool are taken. No other reason is possible,
+ *     because function does not call any memory allocation function.
+ */
 int ul_uniqid_pool_alloc_one_after(ul_uniqid_pool_t *pool, ul_uniqid_t *ptrid, ul_uniqid_t afterid)
 {
   ul_uniqid_t id;
@@ -212,6 +284,7 @@ int ul_uniqid_pool_alloc_one_after(ul_uniqid_pool_t *pool, ul_uniqid_t *ptrid, u
     item->range.first=id+1;
   }else{
     ul_uniqid_pool_delete(pool, item);
+    free(item);
   }
   *ptrid=id;
   
@@ -219,6 +292,15 @@ int ul_uniqid_pool_alloc_one_after(ul_uniqid_pool_t *pool, ul_uniqid_t *ptrid, u
 }
 
 
+/**
+ * ul_uniqid_pool_free_one - Release One Previously Allocated Unique ID
+ * @pool:      the pointer to the unique IDs pool
+ * @id:                the released ID value
+ *
+ * Return Value: The zero value indicates success. The value of -1 indicates,
+ *     that ID cannot be return back, because there is no free memory
+ *     to allocate space for range representing returned ID.
+ */
 int ul_uniqid_pool_free_one(ul_uniqid_pool_t *pool, ul_uniqid_t id)
 {
   return ul_uniqid_pool_release(pool, id, id);