1 files changed, 34 insertions, 8 deletions

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]