From 3b0217d2a2d4e345a31a68948dfb0feaec4a8a2a Mon Sep 17 00:00:00 2001
From: Teddy <ted.sybil@gmail.com>
Date: Sat, 17 Aug 2013 16:49:43 +0800
Subject: more doc

---
 gc.h | 70 +++++++++++++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 44 insertions(+), 26 deletions(-)

(limited to 'gc.h')

diff --git a/gc.h b/gc.h
index ad8ac6b..09687d3 100644
--- a/gc.h
+++ b/gc.h
@@ -11,21 +11,21 @@ typedef std::set<EvalObj*> EvalObjSet;
 class GarbageCollector;
 
 #define GC_CYC_TRIGGER(ptr) \
-do { \
-    if ((ptr) && (ptr)->is_container() &&  \
-            !(static_cast<Container*>(ptr)->keep)) \
-    { \
-        static_cast<Container*>(ptr)->keep = true; \
-        *tail++ = (ptr); \
-    } \
-} while (0)
+    do { \
+        if ((ptr) && (ptr)->is_container() &&  \
+                !(static_cast<Container*>(ptr)->keep)) \
+        { \
+            static_cast<Container*>(ptr)->keep = true; \
+            *tail++ = (ptr); \
+        } \
+    } while (0)
 
 #define GC_CYC_DEC(ptr) \
-do { \
-    if ((ptr) && (ptr)->is_container()) \
+    do { \
+        if ((ptr) && (ptr)->is_container()) \
         static_cast<Container*>(ptr)->gc_refs--; \
-} while (0)
-    
+    } while (0)
+
 extern GarbageCollector gc;
 #define EXIT_CURRENT_ENVT(lenvt) \
     do { \
@@ -48,13 +48,23 @@ extern GarbageCollector gc;
         gc.collect(); \
     } while (0)
 
-struct ObjEntry {
-    EvalObj *obj;
-    size_t gc_cnt;
-    ObjEntry *prev, *next;
-    ObjEntry(ObjEntry *prev, ObjEntry *next);
+/** @class GCRecord 
+ * The record object which keeps track of the GC info of corresponding
+ * EvalObj
+ */
+struct GCRecord {
+    EvalObj *obj;           /**< The pointer to the EvalObj */
+    size_t gc_cnt;          /**< Reference counter */
+    GCRecord *prev;         /**< Previous GCRecord in the list */
+    GCRecord *next;         /**< Next GCRecord in the the list */
+    /** The constructor */
+    GCRecord(GCRecord *prev, GCRecord *next);
 };
 
+/** @class GarbageCollector
+ * Which takes the responsibility of taking care of all existing EvalObj
+ * in use as well as recycling those aren't
+ */
 class GarbageCollector {
 
     struct PendingEntry {
@@ -63,23 +73,31 @@ class GarbageCollector {
         PendingEntry(EvalObj *obj, PendingEntry *next);
     };
 
-    ObjEntry *joined;
+    GCRecord *joined;
     PendingEntry *pending_list;
     size_t resolve_threshold;
     size_t joined_size;
 
-    public:
-
-    GarbageCollector();
-    void collect();
     void cycle_resolve();
     void force();
-    void expose(EvalObj *ptr);
-    void set_resolve_threshold(size_t new_thres);
-    ObjEntry *join(EvalObj *ptr);
+
+    public:
+
+    GarbageCollector();         /**< The constructor */
+    void collect();             /**< To detect and recycle the garbage */
+    /**< Call this when a pointer is attached to the EvalObj */
+    EvalObj *attach(EvalObj *ptr);
+    void expose(EvalObj *ptr);  /**< Call this when a pointer is detached
+                                  from the EvalObj */
+    /** Call this when an EvalObj first appears */ 
+    GCRecord *join(EvalObj *ptr);  
+    /** Call this when an EvalObj is destroyed */
     void quit(EvalObj *ptr);
+
+    /** Get the number of EvalObj in use */
     size_t get_remaining();
-    EvalObj *attach(EvalObj *ptr);
+    /** Set the threshold for cycle_resolve */
+    void set_resolve_threshold(size_t new_thres);
 };
 
 
-- 
cgit v1.2.3