Address Ion's comments

common.h

@@ -25,6 +25,18 @@
     }                                      \
   } while (0);
 
+/* Return and error codes. */
+
+/* If a fatal error happens, the process exits with an exit code. */
+
+#define GIVE_UP(STATUS_CODE) \
+  do { \
+    LOG_ERR("Giving up with status code %d", STATUS_CODE); \
+    exit(STATUS_CODE); \
+  } while (0);
+
+/* Unique IDs */
+
 #define UNIQUE_ID_SIZE 20
 
 typedef struct { unsigned char id[UNIQUE_ID_SIZE]; } unique_id;

event_loop.c

@@ -21,12 +21,12 @@ int64_t event_loop_attach(event_loop *loop,
                           int type,
                           void *data,
                           int fd,
-                          int events) {
+                          int events_tag) {
   assert(utarray_len(loop->items) == utarray_len(loop->waiting));
   int64_t index = utarray_len(loop->items);
   event_loop_item item = {.type = type, .data = data};
   utarray_push_back(loop->items, &item);
-  struct pollfd waiting = {.fd = fd, .events = events};
+  struct pollfd waiting = {.fd = fd, .events = events_tag};
   utarray_push_back(loop->waiting, &waiting);
   return index;
 }

event_loop.h

@@ -1,6 +1,12 @@
 #ifndef EVENT_LOOP_H
 #define EVENT_LOOP_H
 
+/* This header defines the data structure and methods for an event loop.
+ * The event loop allows user code to listen to reads and writes that happen
+ * on file descriptors. We are using this for async io with the database
+ * that holds the state and to communicate between object stores, worker
+ * processes and the local scheduler. */
+
 #include <poll.h>
 #include <stdint.h>
 
@@ -13,6 +19,9 @@ typedef struct {
   void *data;
 } event_loop_item;
 
+/* This is the main event loop datastructure which holds the pollfd struct
+ * for the poll system call and also user data associated with connections
+ * (like the status) of the connection. */
 typedef struct {
   /* Array of event_loop_items that hold information for connections. */
   UT_array *items;
@@ -27,7 +36,7 @@ int64_t event_loop_attach(event_loop *loop,
                           int type,
                           void *data,
                           int fd,
-                          int events);
+                          int events_tag);
 void event_loop_detach(event_loop *loop, int64_t index, int shall_close);
 int event_loop_poll(event_loop *loop);
 int64_t event_loop_size(event_loop *loop);

state/db.h

@@ -15,7 +15,7 @@ void db_connect(const char *db_address,
                 int client_port,
                 db_conn *db);
 
-/* Attach global system store onnection to event loop. Returns the index of the
+/* Add the global system store onnection to event loop. Returns the index of the
  * connection in the loop. */
 int64_t db_attach(db_conn *db, event_loop *loop, int connection_type);