misc comments and cleanups

codes/codes-workload.h

@@ -4,7 +4,10 @@
  *
  */
 
-/* I/O workload generator API to be used by storage simulations */
+/* I/O workload generator API to be used for reading I/O operations into 
+ * storage system simulations.  This API just describes the operations to be
+ * executed; it does not service the operations.
+ */
 
 #ifndef CODES_WORKLOAD_H
 #define CODES_WORKLOAD_H
@@ -37,8 +40,10 @@ struct codes_workload_op
      * between different APIs?
      */
 
+    /* what type of operation this is */
     enum codes_workload_op_type op_type;
 
+    /* parameters for each operation type */
     union
     {
         struct {

src/workload/codes-workload-method.h

@@ -4,9 +4,9 @@
  *
  */
 
-/* I/O workload generator API to be used by workload generators.  It mimics
- * the top level codes-workload.h API, except that there is no reverse
- * handler.
+/* I/O workload generator API to be used by workload generator methods.  
+ * It mimics the top level codes-workload.h API, except that there is no 
+ * reverse handler.
  */
 
 #ifndef CODES_WORKLOAD_METHOD_H

src/workload/codes-workload.c

@@ -17,7 +17,11 @@ extern struct codes_workload_method test_workload_method;
 static struct codes_workload_method *method_array[] = 
     {&test_workload_method, NULL};
 
-/* NOTE: we could make this faster with a smarter data structure.  For now
+/* This shim layer is responsible for queueing up reversed operations and
+ * re-issuing them so that the underlying workload generator method doesn't
+ * have to worry about reverse events.
+ *
+ * NOTE: we could make this faster with a smarter data structure.  For now
  * we just have a linked list of rank_queue structs, one per rank that has
  * opened the workload.  We then have a linked list off of each of those
  * to hold a lifo queue of operations that have been reversed for that rank.

src/workload/test-workload-method.c

@@ -15,8 +15,8 @@
 #include "codes/codes-workload.h"
 #include "codes-workload-method.h"
 
-int test_workload_load(const char* params, int rank);
-void test_workload_get_next(int rank, struct codes_workload_op *op);
+static int test_workload_load(const char* params, int rank);
+static void test_workload_get_next(int rank, struct codes_workload_op *op);
 
 /* state information for each rank that is retrieving requests */
 struct wkload_stream_state
@@ -30,6 +30,7 @@ struct wkload_stream_state
 
 struct wkload_stream_state* wkload_streams = NULL;
 
+/* fill in function pointers for this method */
 struct codes_workload_method test_workload_method = 
 {
     .method_name = "test",
@@ -37,7 +38,7 @@ struct codes_workload_method test_workload_method =
     .codes_workload_get_next = test_workload_get_next,
 };
 
-int test_workload_load(const char* params, int rank)
+static int test_workload_load(const char* params, int rank)
 {
     /* no params in this case; this example will work with any number of
      * ranks
@@ -50,7 +51,7 @@ int test_workload_load(const char* params, int rank)
 
     new->rank = rank;
 
-    /* synthetic workload for testing */
+    /* arbitrary synthetic workload for testing purposes */
     new->op_array_len = 2;
     new->op_array_index = 0;
     new->op_array[0].op_type = CODES_WK_OPEN;
@@ -67,7 +68,8 @@ int test_workload_load(const char* params, int rank)
     return(0);
 }
 
-void test_workload_get_next(int rank, struct codes_workload_op *op)
+/* find the next workload operation to issue for this rank */
+static void test_workload_get_next(int rank, struct codes_workload_op *op)
 {
     struct wkload_stream_state* tmp = wkload_streams;
     struct wkload_stream_state* tmp2 = wkload_streams;

tests/workload/codes-workload-test-cn-lp.c

@@ -30,9 +30,9 @@ enum client_event_type
 
 struct client_state
 {
-    int my_rank;
-    int wkld_id;
-    int target_barrier_count;
+    int my_rank; /* rank of this compute node */
+    int wkld_id; /* identifier returned by workload load fn */
+    int target_barrier_count;  /* state information for handling barriers */
     int current_barrier_count;
 };