Minor cleanup; added error printing functionality to stdout_printer.

4 files changed, 45 insertions, 12 deletions

diff --git a/run.py b/run.py
index ad9a6e0..fc758e5 100755
--- a/run.py
+++ b/run.py
@@ -30,5 +30,5 @@ g4 = [
 # Pipeline
 ###############################################################################
 
-stream = trace_reader.get_trace_record_stream(g4)
-stdout_printer.print_stream(stream)
+stream = trace_reader.trace_reader(g4)
+stdout_printer.stdout_printer(stream)
diff --git a/runtests.py b/runtests.py
index 06c5caa..f4a9274 100755
--- a/runtests.py
+++ b/runtests.py
@@ -31,7 +31,7 @@ files = [
 
 # Does the trace reader sort files by time correctly?
 def test1():
-    stream = trace_reader.get_trace_record_stream(files)
+    stream = trace_reader.trace_reader(files)
     last_time = 0
     for item in stream:
         if last_time > item.when:
diff --git a/stdout_printer.py b/stdout_printer.py
index 98e91fa..1bc0d64 100644
--- a/stdout_printer.py
+++ b/stdout_printer.py
@@ -8,10 +8,12 @@
 # Public functions
 ###############################################################################
 
-def print_stream(stream):
+def stdout_printer(stream):
     for record in stream:
         if record.record_type == "event":
             _print_event(record)
+        elif record.record_type == "error":
+            _print_error(record)
         print("")
 
 ###############################################################################
@@ -22,3 +24,8 @@ def _print_event(record):
     print("Job: {}.{}".format(record.pid,record.job))
     print("Type: {}".format(record.type_name))
     print("Time: {}".format(record.when))
+
+def _print_error(record):
+    print("Job: {}.{}".format(record.pid,record.job))
+    print("Time: {}".format(record.when))
+    print("Type: {}".format("ERROR"))
diff --git a/trace_reader.py b/trace_reader.py
index a0a32ce..7b579b6 100644
--- a/trace_reader.py
+++ b/trace_reader.py
@@ -2,9 +2,24 @@
 # Description
 ###############################################################################
 
-# get_trace_record_stream(files) returns an iterator which produces records
-#     in order from the files given. (the param is a list of files.)
-
+# trace_reader(files) returns an iterator which produces records
+# in order from the files given. (the param is a list of files.)
+#
+# Each record is just a Python object. It is guaranteed to have the following 
+# attributes:
+#   - 'pid': pid of the task
+#   - 'job': job number for that task
+#   - 'cpu', given by LITMUS
+#   - 'when', given by LITMUS as a timestamp. LITMUS does not provide a
+#       timestamp for all records. In this case, when is set to 0.
+#   - 'type', a numerical value given by LITMUS
+#   - 'type_name', a human-readable name defined in this module
+#   - 'record_type', set to 'event' by this module (to distinguish from, e.g.,
+#       error records produced elsewhere).
+#   - Possible additional attributes, depending on the type of record.
+#
+# To find out exactly what attributes are set for each record type, look at
+#     the trace-parsing information at the bottom of this file.
 
 ###############################################################################
 # Imports
@@ -18,7 +33,7 @@ import struct
 ###############################################################################
 
 # Generator function returning an iterable over records in a trace file.
-def get_trace_record_stream(files):
+def trace_reader(files):
 
     # Create iterators for each file and a buffer to store records in
     file_iters = [] # file iterators
@@ -29,7 +44,7 @@ def get_trace_record_stream(files):
         file_iter_buff.append([next(file_iter)])
 
     # We keep 100 records in each buffer and then keep the buffer sorted
-    # This is because records may be recorded slightly out of order
+    # This is because records may have been recorded slightly out of order
     for x in range(0,len(file_iter_buff)):
         for y in range(0,100):
             file_iter_buff[x].append(next(file_iters[x])) 
@@ -89,7 +104,11 @@ def _get_file_iter(file):
                 f.close()
                 print("Invalid record detected, stopping.")
                 exit()
+
+            # Convert the record_dict into an object
             record = _dict2obj(record_dict)
+
+            # Give it a type name (easier to work with than type number)
             record.type_name = _get_type_name(type_num)
 
             # All records should have a 'record type' field.
@@ -114,6 +133,12 @@ def _dict2obj(d):
 # Trace record data types and accessor functions
 ###############################################################################
 
+# Each class below represents a type of event record. The format attribute
+# specifies how to decode the binary record and the keys attribute
+# specifies how to name the pieces of information decoded. Note that all
+# event records have a common initial 24 bytes, represented by the StHeader
+# class.
+
 RECORD_HEAD_SIZE = 24
 
 class StHeader:
@@ -190,8 +215,9 @@ def _get_type(type_num):
              StResumeData,StSysReleaseData]
     return types[type_num]
 
-# Return the type name, given the type_num
+# Return the type name, given the type_num (this is simply a convenience to
+#     programmers of other modules)
 def _get_type_name(type_num):
-    type_names = [None,"name","params","release","assign","switch_to","switch_away",
-        "completion","block","resume","sys_release"]
+    type_names = [None,"name","params","release","assign","switch_to",
+        "switch_away","completion","block","resume","sys_release"]
     return type_names[type_num]