forb: Split forb_port_destroy() to stop and destroy phases

[frescor/forb.git] / src / refcnt.c

diff --git a/src/refcnt.c b/src/refcnt.c
index 3b29b7e97b8d486f01ade50527f4fc570e3c6379..9c76737996f2608dd3ee2c437df56b9316d768b5 100644 (file)
--- a/src/refcnt.c
+++ b/src/refcnt.c
@@ -51,7 +51,7 @@
  * 
  * @brief  Atomic reference counting operations.
  *
- * @note: To provide portable atomicity, we use GCC's builtin
+ * @note To provide portable atomicity, we use GCC's builtin
  * functions introduced in GCC 4.1.
  * 
  */
@@ -62,16 +62,37 @@ void forb_ref_set(struct forb_ref *ref, int num)
        ref->refcount = num;
 }
 
+/** 
+ * Initializes reference count to 1.
+ * 
+ * @param ref 
+ */
 void forb_ref_init(struct forb_ref *ref)
 {
        forb_ref_set(ref, 1);
 }
 
+/** 
+ * Atomicaly increases reference count
+ * 
+ * @param ref 
+ */
 void forb_ref_get(struct forb_ref *ref)
 {
        __sync_add_and_fetch(&ref->refcount, 1);
 }
 
+/** 
+ * Atomicaly decreases reference count and if zero is reached calls, @a
+ * release function (destructor).
+ * 
+ * @param ref Reference to act on.
+ * @param release Release function called when reference count reaches zero.
+ * 
+ * @return 1 if the @a release function was called, zero othewise
+ * (which doesn't mean that the object still exist in memory as it
+ * might be released by somebody else in the mean time).
+ */
 int forb_ref_put(struct forb_ref *ref, void (*release) (struct forb_ref *ref))
 {
        if (__sync_add_and_fetch(&ref->refcount, -1) == 0) {