Documented the library

src/GC/tests/extern_lib.cpp

@@ -7,40 +7,6 @@ GC::Heap *singleton_test();
 void init_gc(GC::Heap *heap);
 void frame_test(GC::Heap *heap);
 
-GC::Heap *singleton_test() {
-    std::cout << "TESTING SINGLETON INSTANCES" << std::endl;
-    std::cout << "===========================" << std::endl;
-    std::cout << "Call 1:\t" << GC::Heap::the() << std::endl;
-    GC::Heap *heap = GC::Heap::the();
-    std::cout << "Call 2:\t" << heap << std::endl;
-    std::cout << "===========================" << std::endl;
-    return heap;
-}
-
-void init_gc(GC::Heap *heap){
-    std::cout << "\n\n   INITIALIZING THE HEAP" << std::endl;
-    std::cout << "===========================" << std::endl;
-    heap->init();
-    std::cout << "===========================" << std::endl;
-}
-
-void frame_test(GC::Heap *heap) {
-    std::cout << "\n\n  TESTING FRAME ADDRESSES" << std::endl;
-    std::cout << "===========================" << std::endl;
-
-#pragma clang diagnostic ignored "-Wframe-address"
-    auto curr_frame = reinterpret_cast<uintptr_t *>(__builtin_frame_address(0));
-    std::cout << "Current stack frame:\t" << curr_frame << std::endl;
-#pragma clang diagnostic ignored "-Wframe-address"
-    auto prev_frame = reinterpret_cast<uintptr_t *>(__builtin_frame_address(1));
-    std::cout << "Previous stack frame:\t" << prev_frame << std::endl;
-
-    heap->check_init();
-    // auto alloced = heap->alloc(sizeof(unsigned long));
-    
-    std::cout << "===========================" << std::endl;
-}
-
 int main() {
     std::cout << "in main" << std::endl;
     auto heap = singleton_test();
@@ -49,4 +15,77 @@ int main() {
     frame_test(heap);
 
     return 0;
+}
+
+/**
+ * This test is supposed to determine if the singleton pattern
+ * implementation is working correctly. This test passes if the
+ * first and second call prints the same memory address.
+ * 
+ * Result: pass
+ * 
+ * @return Pointer to the Heap singleton instance
+*/
+GC::Heap *singleton_test() {
+    std::cout << "TESTING SINGLETON INSTANCES" << std::endl;
+    std::cout << "===========================" << std::endl;
+    std::cout << "Call 1:\t" << GC::Heap::the() << std::endl;   // First call which initializes the singleton instance
+    GC::Heap *heap = GC::Heap::the();                           // Second call which should return the initialized instance
+    std::cout << "Call 2:\t" << heap << std::endl;
+    std::cout << "===========================" << std::endl;
+    return heap;
+}
+
+
+/**
+ * This test calls Heap::init() which saves the stack-frame
+ * address from the calling function (this function).
+ * Heap::init() is supposed to be called at the absolute
+ * start of the program to save the address of the
+ * topmost stack frame. This test doesn't do anything
+ * but prepares for the next test(s).
+ * 
+ * @param heap The Heap pointer to the singleton instance.
+ * 
+*/
+void init_gc(GC::Heap *heap){
+    std::cout << "\n\n   INITIALIZING THE HEAP" << std::endl;
+    std::cout << "===========================" << std::endl;
+    heap->init();
+    std::cout << "===========================" << std::endl;
+}
+
+/**
+ * This function tests the functionality of the intrinsic
+ * function `__builtin_frame_address` which returns the
+ * address of the corresponding level of stack frame.
+ * When given a param of 0, it returns the current stack frame.
+ * When given a param of 1, it returns the previous stack
+ * frame, and so on.
+ * 
+ * This test passes on two conditions:
+ * 1)   if the address of the current frame is smaller than
+ *      the address of the previous frame (assumed).
+ * 2)   if the previous frame has the same address as the one
+ *      saved in the Heap instance after running Heap::init().
+ * 
+ * Result: pass 
+ * 
+ * @param heap The Heap instance
+*/
+void frame_test(GC::Heap *heap) {
+    std::cout << "\n\n  TESTING FRAME ADDRESSES" << std::endl;
+    std::cout << "===========================" << std::endl;
+
+#pragma clang diagnostic ignored "-Wframe-address" // clang++ directive to ignore warnings about __b_f_a
+    auto curr_frame = reinterpret_cast<uintptr_t *>(__builtin_frame_address(0)); // addr of curr stack frame
+    std::cout << "Current stack frame:\t" << curr_frame << std::endl;
+#pragma clang diagnostic ignored "-Wframe-address"
+    auto prev_frame = reinterpret_cast<uintptr_t *>(__builtin_frame_address(1)); // addr of prev stack frame
+    std::cout << "Previous stack frame:\t" << prev_frame << std::endl;
+
+    heap->check_init(); // prints the saved absolute top of the stack
+    // auto alloced = heap->alloc(sizeof(unsigned long));
+    
+    std::cout << "===========================" << std::endl;
 }

src/GC/tests/h_test.cpp

@@ -35,7 +35,7 @@ void detach_pointer(long **ptr) {
     *ptr = dummy_ptr;
 }
 
-void test_chain(int depth, bool detach) {
+Node *test_chain(int depth, bool detach) {
     auto stack_start = reinterpret_cast<uintptr_t *>(__builtin_frame_address(0));
     std::cout << "Stack start from test_chain:\t" << stack_start << std::endl;
 
@@ -43,6 +43,7 @@ void test_chain(int depth, bool detach) {
     // This generates a segmentation fault (should be investigated further)
     if (detach)
         node_chain->child = nullptr;
+    return node_chain;
 
 }
 
@@ -63,8 +64,8 @@ void test_some_types() {
 }
 
 int main() {
-    //gc->init();
-    //gc->check_init();
+    gc->init();
+    gc->check_init();
     auto stack_start = reinterpret_cast<uintptr_t *>(__builtin_frame_address(0));
     std::cout << "Stack start from main:\t" << stack_start << std::endl;
     
@@ -74,13 +75,20 @@ int main() {
     // long *l = static_cast<long *>(gc->alloc(sizeof(long))); // 0x6-0xd  | 0x
     
     // This is allocated outside of the scope of the GC (if gc->init() isn't called), thus garbage
-    long *longs[21];
+    /* long *longs[21];
     std::cout << "Pointer to ints:\t" << longs << std::endl;
     for (int i = 0; i < 21; i++) {
         longs[i] = static_cast<long *>(gc->alloc(sizeof(long)));
-    }
+    } */
+    //Node *root;
+    Node *root = test_chain(3, false);
+    std::cout << "Adress of root:\t" << &root << std::endl;
+    std::cout << "Root points to:\t" << root << std::endl;
+    // 0x7ffdd7556bd8
+    int *i = static_cast<int *>(gc->alloc(sizeof(int)));
+    std::cout << "Adress of i:\t" << &i << std::endl;
 
-    gc->collect(MARK | SWEEP | FREE); // free misses some chunks
+    gc->collect(MARK); // free misses some chunks
     gc->print_contents();
     return 0;
 }