From: ppisa <ppisa>
Date: Tue, 24 Jan 2006 11:18:24 +0000 (+0000)
Subject: Structured comment added to unique IDs pool code and some memory leak correction.
X-Git-Tag: ul_drv-0.8.0-release~49
X-Git-Url: https://rtime.felk.cvut.cz/gitweb/ulut.git/commitdiff_plain/8c2db66b8796f8691c49a62dc6cdf5b0852e3226?hp=cf324a881ec9e5533fc05b9db8e8bd9a7b16a18c

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

diff --git a/ulut/ul_evcbase.c b/ulut/ul_evcbase.c
index 5d1eb21..353b6e4 100644
--- a/ulut/ul_evcbase.c
+++ b/ulut/ul_evcbase.c
@@ -245,7 +245,7 @@ int evc_tx_hub_init(evc_tx_hub_t *hub)
 }
 
 /**
- * evc_tx_hub_done - Initializes Event Transmition Hub
+ * evc_tx_hub_done - Finalize Event Transmition Hub
  * @hub:	pointer to the &evc_tx_hub_t type hub
  */
 void evc_tx_hub_done(evc_tx_hub_t *hub)
diff --git a/ulut/ul_uniqid.c b/ulut/ul_uniqid.c
index 64ad4f9..4b0e9f4 100644
--- 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);
diff --git a/ulut/ul_uniqid.h b/ulut/ul_uniqid.h
index b19ab02..32de471 100644
--- a/ulut/ul_uniqid.h
+++ b/ulut/ul_uniqid.h
@@ -29,12 +29,26 @@
 
 typedef unsigned long ul_uniqid_t;
 
-typedef struct ul_uniqid_range {
+typedef struct ul_uniqid_range_t {
   ul_uniqid_t first;
   ul_uniqid_t last;
 } ul_uniqid_range_t;
 
-typedef struct ul_uniqid_pool {
+/**
+ * struct ul_uniqid_pool_t - The Unique Identifiers Pool
+ * @items:	GAVL tree of not allocated yet ranges
+ * @range:	numeric range to allocate IDs from
+ *
+ * The unique pool provides functions to manage unique numerical IDs.
+ * The pool is first initialized by function ul_uniqid_pool_init().
+ * The available range is specified at this time. The pool can be
+ * flushed and destroyed by call ul_uniqid_pool_done().
+ *
+ * The function ul_uniqid_pool_alloc_one() returns first free ID from
+ * range. The ID is returned to the pool by function ul_uniqid_pool_free_one().
+ * There are even functions to reserve and release specific IDs range.
+ */
+typedef struct ul_uniqid_pool_t {
   gavl_fles_int_root_field_t items;
   ul_uniqid_range_t range;
 } ul_uniqid_pool_t;