From 91858522369751613b74cb3983484d7c85266730 Mon Sep 17 00:00:00 2001
From: Sean McBride <spmcbride1201@gmail.com>
Date: Tue, 18 Feb 2020 21:04:09 -0500
Subject: [PATCH] docs: Add documentation to code (#7)

---
 runtime/include/types.h |  4 ++--
 runtime/src/http.c      |  3 +++
 runtime/src/main.c      | 10 ++++++----
 runtime/src/runtime.c   | 17 +++++++++++++++++
 runtime/src/util.c      |  4 ++++
 5 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/runtime/include/types.h b/runtime/include/types.h
index c64ef69..fcd161c 100644
--- a/runtime/include/types.h
+++ b/runtime/include/types.h
@@ -142,8 +142,8 @@ typedef enum
 
 #define RDWR_VEC_MAX 16
 
-#define MOD_REQ_CORE  0                                  // core dedicated to check module requests..
-#define SBOX_NCORES   (NCORES > 1 ? NCORES - 1 : NCORES) // number of sandboxing threads
+#define MOD_REQ_CORE  0                                  // Dedicated Listener Core
+#define SBOX_NCORES   (NCORES > 1 ? NCORES - 1 : NCORES) // If multicore, use all but the dedicated listener core
 #define SBOX_MAX_REQS (1 << 19)                          // random!
 
 #define SBOX_RESP_STRSZ 32
diff --git a/runtime/src/http.c b/runtime/src/http.c
index df5ae80..bc8273e 100644
--- a/runtime/src/http.c
+++ b/runtime/src/http.c
@@ -221,6 +221,9 @@ http_request_parse_sb(struct sandbox *s, size_t l)
 	return 0;
 }
 
+/**
+ * Configure Callback Functions for HTTP Events
+ */
 void
 http_init(void)
 {
diff --git a/runtime/src/main.c b/runtime/src/main.c
index 37580ad..ad405fc 100644
--- a/runtime/src/main.c
+++ b/runtime/src/main.c
@@ -12,13 +12,15 @@
 #include <sys/time.h>
 #include <sys/resource.h>
 
+// TODO: I think this define is unused
 #define MOD_LINE_MAX 1024
 
-i32 logfd = -1;
+i32 logfd = -1; 	  // Log File Descriptor
+u32 ncores = 0; 	  // Number of cores
+u32 sbox_ncores = 0;  // Number of Sandboxing Cores
+u32 sbox_core_st = 0; // First Sandbox Core 
 
-u32 ncores = 0, sbox_ncores = 0, sbox_core_st = 0;
-
-pthread_t rtthd[SBOX_NCORES];
+pthread_t rtthd[SBOX_NCORES]; // An array of runtime threads
 
 static unsigned long long
 get_time()
diff --git a/runtime/src/runtime.c b/runtime/src/runtime.c
index 940f5f8..7958a4e 100644
--- a/runtime/src/runtime.c
+++ b/runtime/src/runtime.c
@@ -281,6 +281,15 @@ sandbox_exit(void)
 #endif
 }
 
+/**
+ * @brief Execution Loop of the listener core, handles HTTP requests, allocates sandbox request objects, and pushes the sandbox object to the global dequeue
+ * @param d Unknown
+ * @return NULL
+ * 
+ * Used Globals:
+ * epfd - the epoll file descriptor
+ * 
+ */
 void *
 runtime_accept_thdfn(void *d)
 {
@@ -319,6 +328,9 @@ runtime_accept_thdfn(void *d)
 	return NULL;
 }
 
+/**
+ * Initialize runtime global state, mask signals, and init http server
+ */
 void
 runtime_init(void)
 {
@@ -326,6 +338,8 @@ runtime_init(void)
 	assert(epfd >= 0);
 	glb_dq = (struct deque_sandbox *)malloc(sizeof(struct deque_sandbox));
 	assert(glb_dq);
+
+	// Note: Below is a Macro
 	deque_init_sandbox(glb_dq, SBOX_MAX_REQS);
 
 	softint_mask(SIGUSR1);
@@ -334,6 +348,9 @@ runtime_init(void)
 	http_init();
 }
 
+/**
+ * Initializes the listener thread, pinned to core 0, and starts to listen for requests
+ */
 void
 runtime_thd_init(void)
 {
diff --git a/runtime/src/util.c b/runtime/src/util.c
index 4191319..90f3f3f 100644
--- a/runtime/src/util.c
+++ b/runtime/src/util.c
@@ -23,6 +23,10 @@ util_remove_spaces(char *str)
 }
 
 
+/**
+ * Parses a JSON file and allocates one or more new modules
+ * @param filename The path of the JSON file
+ */
 int
 util_parse_modules_file_json(char *filename)
 {