From 01c93a631f5920fcfcf05bb86c4876170311cabc Mon Sep 17 00:00:00 2001
From: Victor Olin <victor.vieweg@icloud.com>
Date: Wed, 29 Mar 2023 21:27:47 +0200
Subject: [PATCH] Wrapper docs

---
 src/GC/Makefile          | 20 ++++++++++++--------
 src/GC/docs/lib/cheap.md | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 8 deletions(-)
 create mode 100644 src/GC/docs/lib/cheap.md

diff --git a/src/GC/Makefile b/src/GC/Makefile
index 1fda452..f66f692 100644
--- a/src/GC/Makefile
+++ b/src/GC/Makefile
@@ -55,9 +55,9 @@ static_lib:
 # remove old files
 	rm -f lib/event.o lib/profiler.o lib/heap.o lib/gcoll.a tests/extern_lib.out
 # compile object files
-	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -g -c -o lib/event.o lib/event.cpp -fPIC
-	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -g -c -o lib/profiler.o lib/profiler.cpp -fPIC
-	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -g -c -o lib/heap.o lib/heap.cpp -fPIC
+	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -c -o lib/event.o lib/event.cpp -fPIC
+	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -c -o lib/profiler.o lib/profiler.cpp -fPIC
+	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -c -o lib/heap.o lib/heap.cpp -fPIC
 # create static library
 	ar r lib/gcoll.a lib/event.o lib/profiler.o lib/heap.o
 
@@ -65,11 +65,15 @@ static_lib:
 static_lib_test: static_lib
 	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -o tests/extern_lib.out tests/extern_lib.cpp lib/gcoll.a
 
-wrapper: 
+wrapper:
+# remove old files 
 	rm -f lib/event.o lib/profiler.o lib/heap.o lib/coll.a tests/wrapper.out
-	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -g -c -o lib/event.o lib/event.cpp -fPIC
-	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -g -c -o lib/profiler.o lib/profiler.cpp -fPIC
-	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -g -c -o lib/heap.o lib/heap.cpp -fPIC
-	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -g -c -o lib/cheap.o lib/cheap.cpp -fPIC
+# compile object files
+	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -c -o lib/event.o lib/event.cpp -fPIC
+	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -c -o lib/profiler.o lib/profiler.cpp -fPIC
+	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -c -o lib/heap.o lib/heap.cpp -fPIC
+	$(CC) $(STDFLAGS) $(WFLAGS) $(LIB_INCL) -O3 -c -o lib/cheap.o lib/cheap.cpp -fPIC
+# compile object files into library
 	ar rcs lib/gcoll.a lib/event.o lib/profiler.o lib/heap.o lib/cheap.o
+# compile test program wrapper.c with normal clang
 	clang -stdlib=libc++ $(WFLAGS) $(LIB_INCL) -o tests/wrapper.out tests/wrapper.c lib/gcoll.a -lstdc++
diff --git a/src/GC/docs/lib/cheap.md b/src/GC/docs/lib/cheap.md
new file mode 100644
index 0000000..e5c5993
--- /dev/null
+++ b/src/GC/docs/lib/cheap.md
@@ -0,0 +1,40 @@
+# cheap.h & cheap.cpp
+
+A wrapper interface for the class `GC::Heap` for easier use
+in LLVM (no nasty namespaces). This interface is relatively
+straight-forward and only defines functions to use the already
+public functions in the class `GC::Heap`.
+
+The functions are declared in a normal C-style header and
+defined as "pure" C-functions. Because the public functions
+exposed in `GC::Heap` are static, some of the functions
+just call the static functions but are wrapped as C-functions.
+
+For the non-static function `GC::Heap::set_profiler()` and the
+singleton get-instance function `GC::Heap::the()` a struct
+is used to encapsulate the heap-object. If this library is
+compiled with `DEBUG` defined a struct is typedef-ed and
+can be used everywhere, otherwise this struct is opaque
+and cannot be used explicitly. This struct only contains
+a pointer to the heap instance and is called `cheap_t`.
+
+## Functions
+`cheap_t *cheap_the()`: Returns an encapsulated singleton
+instance. It is encapsulated in an opaque struct as the
+instance itself is not meant to be used outside the C++
+library.
+
+`void cheap_init()`: Simply calls the `Heap::init()`
+function.
+
+`void cheap_dispose()`: Only calls the `Heap::dispose()`
+function.
+
+`void *cheap_alloc(unsigned long size)`: Calls `Heap::alloc(size_t size)`
+and returns whatever `alloc` returns.
+
+`void cheap_set_profiler(cheap_t *cheap, bool mode)`:
+The argument `cheap` is the encapsulated Heap singleton instance.
+`mode` is the same as for `Heap::set_profiler(bool mode)`.
+
+For more documentation on functionality, see `src/GC/docs/lib/heap.md`.
\ No newline at end of file