Better documentation

Author: jpalharini

bin/lc-stress-tests-jar.sh

@@ -4,49 +4,45 @@ struct_sizes=(0 1 8 16 32 64 256 1024)
 
 jvm_opts="-server -Xms8g -Xmx8g -XX:+UseZGC"
 
+# each job completion runs in an isolated pod/container, JOB_COMPLETION_INDEX identifies the pod/container
+# this will run a single test per pod, then destroy it
 for size in "${struct_sizes[@]}"; do
   case $JOB_COMPLETION_INDEX in
-    0|1)
-      if (( JOB_COMPLETION_INDEX == 0)); then
-        java $jvm_opts -jar bin/fressian-old.jar "vec" ${size} false
-      else
-        java $jvm_opts -jar bin/fressian-old.jar "map" ${size} false
-      fi
-      ;;
-    2|3)
-      if (( JOB_COMPLETION_INDEX == 2)); then
-        java $jvm_opts -jar bin/fressian-convert.jar "vec" ${size} false
-      else
-        java $jvm_opts -jar bin/fressian-convert.jar "map" ${size} false
-      fi
-      ;;
-    4|5)
-      if (( JOB_COMPLETION_INDEX == 4)); then
-        java $jvm_opts -jar bin/fressian-convert.jar "vec" ${size} true
-      else
-        java $jvm_opts -jar bin/fressian-convert.jar "map" ${size} true
-      fi
-      ;;
-    6|7)
-      if (( JOB_COMPLETION_INDEX == 6)); then
-        java $jvm_opts -jar bin/fressian-reduce.jar "vec" ${size} false
-      else
-        java $jvm_opts -jar bin/fressian-reduce.jar "map" ${size} false
-      fi
-      ;;
-    8|9)
-      if (( JOB_COMPLETION_INDEX == 8)); then
-        java $jvm_opts -jar bin/fressian-reduce.jar "vec" ${size} true
-      else
-        java $jvm_opts -jar bin/fressian-reduce.jar "map" ${size} true
-      fi
-      ;;
-    10|11)
-      if (( JOB_COMPLETION_INDEX == 10)); then
-        java $jvm_opts -jar bin/fressian-reducemap.jar "vec" ${size} true
-      else
-        java $jvm_opts -jar bin/fressian-reducemap.jar "map" ${size} true
-      fi
+    0)
+      java $jvm_opts -jar bin/fressian-old.jar "vec" ${size} false
+      ;;
+    1)
+      java $jvm_opts -jar bin/fressian-old.jar "map" ${size} false
+      ;;
+    2)
+      java $jvm_opts -jar bin/fressian-convert.jar "vec" ${size} false
+      ;;
+    3)
+      java $jvm_opts -jar bin/fressian-convert.jar "map" ${size} false
+      ;;
+    4)
+      java $jvm_opts -jar bin/fressian-convert.jar "vec" ${size} true
+      ;;
+    5)
+      java $jvm_opts -jar bin/fressian-convert.jar "map" ${size} true
+      ;;
+    6)
+      java $jvm_opts -jar bin/fressian-reduce.jar "vec" ${size} false
+      ;;
+    7)
+      java $jvm_opts -jar bin/fressian-reduce.jar "map" ${size} false
+      ;;
+    8)
+      java $jvm_opts -jar bin/fressian-reduce.jar "vec" ${size} true
+      ;;
+    9)
+      java $jvm_opts -jar bin/fressian-reduce.jar "map" ${size} true
+      ;;
+    10)
+      java $jvm_opts -jar bin/fressian-reducemap.jar "vec" ${size} true
+      ;;
+    11)
+      java $jvm_opts -jar bin/fressian-reducemap.jar "map" ${size} true
       ;;
   esac
 done

dev/aux.clj

@@ -55,22 +55,31 @@
      ~@body
      (- (System/nanoTime) st#)))
 
-(defn stress-test [{:keys [struct-type struct-size convert-list?] :as argmap}
-                   read-handlers]
+(defn stress-test
+  "Benchmarks Fressian reading for 20 minutes, repeatedly reading a collection of structs.
+   Generates a log message at the end with total runs and processing time.
+
+   Receives argmap and a collection of Fressian read handlers
+   - struct-type can be map or vec
+   - struct-size is an arbitrary positive integer - if less than 9, repeated reading will use a collection of 1,000
+     structs, else it will use a collection of 100,000 to avoid sub-millisecond measurement as the JVM doesn't promise
+     sub-millisecond resolution
+   - convert-list? determines whether reading will use custom read handlers or defaults"
+  [{:keys [struct-type struct-size convert-list?] :as argmap}
+   read-handlers]
   (let [gen-struct-fn (case (str struct-type)
                         "map" gen-map
                         "vec" gen-vec)
         fr-handlers   (when convert-list? read-handlers)]
     (info (merge {:event :starting-stress-test} argmap))
     (let [work-chan    (async/chan 1)
           timeout-chan (async/timeout (* 1000 60 20))
-          ; avoid submillisecond measurement
           struct-count (* 1000 (if (< struct-size 9)
                                  100 1))]
       (loop [runs      0
              proc-time 0]
         (let [structs (repeatedly struct-count #(gen-struct-fn struct-size))
-              ; put generated structs fressianed into the work channel as a single coll
+              ; put generated structs fressianed into the work channel as a single, eager vector
               _       (async/put! work-chan (into [] (for [st structs] (fressian st))))
               [val port] (async/alts!! [work-chan timeout-chan])]
           (cond