chore: Assorted cleanup

README.md

@@ -63,7 +63,7 @@ To stop the Docker container:
 
 ## Running your first serverless function
 
-An aWsm serverless function consists of a shared library (*.so) and a JSON configuration file that determines how the runtime should execute the serverless function. As an example, here is the configuration file for our sample fibonacci function:. 
+An aWsm serverless function consists of a shared library (\*.so) and a JSON configuration file that determines how the runtime should execute the serverless function. As an example, here is the configuration file for our sample fibonacci function:
 
 ```json
 {
@@ -81,11 +81,11 @@ An aWsm serverless function consists of a shared library (*.so) and a JSON confi
 }
 ```
 
-The `port` and `name` fields are used to determine the path where our serverless function will be served served. 
+The `port` and `name` fields are used to determine the path where our serverless function will be served served.
 
 In our case, we are running the aWsm runtime on localhost, so our function is available at `http://localhost:10000/fibonacci`
 
-Our fibonacci function will parse a single argument from the HTTP POST body that we send. The expected Content-Type  is "text/plain" and the buffer is sized to 1024 bytes for both the request and response. This is sufficient for our simple Fibonacci function, but this must be changed and sized for other functions, such as image processing.
+Our fibonacci function will parse a single argument from the HTTP POST body that we send. The expected Content-Type is "text/plain" and the buffer is sized to 1024 bytes for both the request and response. This is sufficient for our simple Fibonacci function, but this must be changed and sized for other functions, such as image processing.
 
 Now that we understand roughly how the aWsm runtime interacts with serverless function, let's run Fibonacci!
 
@@ -115,8 +115,8 @@ You should receive the following in response. The serverless function says that
 
 ```bash
 HTTP/1.1 200 OK
-Content-length: 3           
-Content-type: text/plain                      
+Content-length: 3
+Content-type: text/plain
 
 55
 ```

runtime/include/types.h

@@ -106,14 +106,12 @@ typedef enum
 #define MOD_TBL_FN  "populate_table"
 #define MOD_LIBC_FN "wasmf___init_libc"
 
-#define MOD_MAX_ARGS   16
-#define MOD_ARG_MAX_SZ 64
-#define MOD_MAX        1024
-
-#define MOD_NAME_MAX 32
-#define MOD_PATH_MAX 256
-
-#define JSON_ELE_MAX 16
+#define MOD_MAX_ARGS     16 // Max number of arguments
+#define MOD_ARG_MAX_SZ   64 // Max size of a single argument
+#define MOD_MAX        1024 // Max size of a single module in JSON
+#define MOD_NAME_MAX 	 32 // Max module name length
+#define MOD_PATH_MAX 	256	// Max module path length
+#define JSON_ELE_MAX 	 16 // Max number of elements defined in JSON
 
 // FIXME: some naive work-stealing here..
 #define SBOX_PULL_MAX 1
@@ -143,7 +141,10 @@ typedef enum
 #define RDWR_VEC_MAX 16
 
 #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
+
+// If multicore, use all but the dedicated listener core
+// If there are fewer cores than this, main dynamically overrides this and uses all available
+#define SBOX_NCORES   (NCORES > 1 ? NCORES - 1 : NCORES) 
 #define SBOX_MAX_REQS (1 << 19)                          // random!
 
 #define SBOX_RESP_STRSZ 32

runtime/src/main.c

@@ -43,8 +43,13 @@ usage(char *cmd)
 int
 main(int argc, char **argv)
 {
+	printf("Starting Awsm\n");
 #ifndef STANDALONE
-	int i = 0, rtthd_ret[SBOX_NCORES] = { 0 };
+	// Array of arguments passed to the start_routine via pthread_create
+	// This is always empty, as we don't pass an argument
+	int rtthd_ret[SBOX_NCORES] = { 0 }; 
+
+	// Initialize the array of runtime threads
 	memset(rtthd, 0, sizeof(pthread_t) * SBOX_NCORES);
 
 	if (argc != 2) {
@@ -52,6 +57,8 @@ main(int argc, char **argv)
 		exit(-1);
 	}
 
+	// Sets the process data segment (RLIMIT_DATA) and # file descriptors 
+	// (RLIMIT_NOFILE) soft limit to its hard limit (see man getrlimit)
 	struct rlimit r;
 	if (getrlimit(RLIMIT_DATA, &r) < 0) {
 		perror("getrlimit RLIMIT_DATA");
@@ -72,7 +79,11 @@ main(int argc, char **argv)
 		exit(-1);
 	}
 
+	// Find the number of processors currently online
 	ncores = sysconf(_SC_NPROCESSORS_ONLN);
+
+	// If multicore, we'll pin one core as a listener and run sandbox threads on all others
+	// If single core, we'll do everything on that one core
 	if (ncores > 1) {
 		u32 x       = ncores - 1;
 		sbox_ncores = SBOX_NCORES;
@@ -84,6 +95,8 @@ main(int argc, char **argv)
 	debuglog("Number of cores %u, sandboxing cores %u (start: %u) and module reqs %u\n", ncores, sbox_ncores,
 	         sbox_core_st, MOD_REQ_CORE);
 
+// If NOSTIO is defined, close stdin, stdout, stderr, and write to logfile named awesome.log. Otherwise, log to STDOUT
+// NOSTIO = No Standard Input/Output?
 #ifdef NOSTDIO
 	fclose(stdout);
 	fclose(stderr);
@@ -98,15 +111,16 @@ main(int argc, char **argv)
 #endif
 
 	runtime_init();
+
 	debuglog("Parsing modules file [%s]\n", argv[1]);
 	if (util_parse_modules_file_json(argv[1])) {
 		printf("failed to parse modules file[%s]\n", argv[1]);
-
 		exit(-1);
 	}
+
 	runtime_thd_init();
 
-	for (i = 0; i < sbox_ncores; i++) {
+	for (int i = 0; i < sbox_ncores; i++) {
 		int ret = pthread_create(&rtthd[i], NULL, sandbox_run_func, (void *)&rtthd_ret[i]);
 		if (ret) {
 			errno = ret;
@@ -122,7 +136,7 @@ main(int argc, char **argv)
 	}
 	debuglog("Sandboxing environment ready!\n");
 
-	for (i = 0; i < sbox_ncores; i++) {
+	for (int i = 0; i < sbox_ncores; i++) {
 		int ret = pthread_join(rtthd[i], NULL);
 		if (ret) {
 			errno = ret;

runtime/src/runtime.c

@@ -15,9 +15,8 @@ struct deque_sandbox *glb_dq;
 pthread_mutex_t       glbq_mtx = PTHREAD_MUTEX_INITIALIZER;
 int                   epfd;
 
-// per-thread (per-core) run and completion queue.. (using doubly-linked-lists)
-__thread static struct ps_list_head runq;
-__thread static struct ps_list_head endq;
+__thread static struct ps_list_head runq; // per-thread(core) run queue (doubly-linked list)
+__thread static struct ps_list_head endq; // per-thread(core) completion queue (doubly-linked list)
 
 // current sandbox that is active..
 __thread sandbox_t *current_sandbox = NULL;
@@ -31,6 +30,10 @@ __thread arch_context_t base_context;
 // libuv i/o loop handle per sandboxing thread!
 __thread uv_loop_t uvio;
 
+/**
+ * Append the sandbox to the runqueue
+ * @param s sandbox to add
+ */
 static inline void
 sandbox_local_run(struct sandbox *s)
 {