tracemultiplexer sample: revise README.md

jon-jacky · jon-jacky · commit 9b46ed161a8d · 2013-04-05T21:43:08.000-07:00
also add test_viewer.py
also revise comment header in tracemultiplexer.py
diff --git a/samples/tracemultiplexer/README.md b/samples/tracemultiplexer/README.md
@@ -2,28 +2,48 @@
 tracemultiplexer
 ================
 
-This model simulates a multi-threaded program that has been
-instrumented to save traces of its API calls in a log.  
+Simulate a program where two threads write to the same log file.
+Investigate synchronization to ensure that only one thread at a
+time can write to the log.
 
-When multiple threads are writing the trace log, there can be
-nondeterminism in the order in which API calls and returns are made, and
-the order they appear in the trace log.  The purpose of this sample is
-to demonstrate that nondeterminism.
+States where both threads may write to the log are considered unsafe
+states.  Marked log messages may have been corrupted by unsynchronized
+writes from both threads.
 
 More details appear in the *tracemultiplexer* comment header.
 
-- *tracemultiplexer*: simulates a multi-threaded program that has been
-  instrumented to save traces of its API calls in a log. 
+- *tracemultiplexer*: model program that simulates a multi-threaded
+  program with and without synchronization.
 
-- *test_graphics* - generate a graph that shows the behavior of *tracemultiplexer*
+- *test_viewer* - generate a graph that shows the behavior of
+  *tracemultiplexer* using a lock to synchronize write access to the
+  log file, and a second graph showing the behavior of
+  *tracemultiplexer* with the *unsynchronized* configuration that
+  ignores the lock.
 
-- *fsmpy*, *svg* - directories of output from the test scripts
+- *fsmpy*, *svg* - directories of output from *test_viewer*
 
-View the generated graphics file in a browser.  Hover the
-pointer over any state bubble to see a tooltip that shows the state
-variables in that state.
+View the generated *.svg* files in a browser.  Hover the pointer over
+any state bubble to see a tooltip that shows the state variables in
+that state.  
+
+The *log* variable represents the log file: it is a list of tuples
+where each tuple represents a log message.  Messages that end with
+*'XXX'* were logged when both threads may have written to the log,
+so the message may have been corrupted by unsynchronized writes.
 
 - *tracemultiplexerFSM* - graph that shows the behavior of *tracemultiplexer*
+  using the lock.  None of the states in this graph are unsafe.  None of the 
+  log messages are marked with *'XXX'*.  
+
+- *unsynchronizedFSM* - graph that shows the behavior of *tracemultiplexer*
+  ignoring the lock.  There are many more transitions and states in this
+  graph because the threads are unsynchronized, so many more interleavings are
+  possible.  There are many unsafe states (colored red) where both threads may
+  write to the log.  In every unsafe state, the most recently written message in 
+  *log* ends with *'XXX'* to indicate it may have been corrupted by 
+  unsynchronized writes.  These corrupted messages persist in *log* in
+  subsequent states.
 
 There is no stepper in this sample.
 
diff --git a/samples/tracemultiplexer/test_viewer.py b/samples/tracemultiplexer/test_viewer.py
@@ -0,0 +1,12 @@
+"""
+tracemultiplexer test - with graphics because this is a model for analysis
+"""
+
+cases = [
+    ('Generate graph for synchronized threads that use tracelock',
+     'pmv.py tracemultiplexer'),
+
+    ('Generate graph for *un*synchronized threads that *ignore* tracelock',
+     'pmv.py -m 300 unsynchronized tracemultiplexer'),
+]
+
diff --git a/samples/tracemultiplexer/tracemultiplexer.py b/samples/tracemultiplexer/tracemultiplexer.py
@@ -1,11 +1,18 @@
 """
-Simulate a multi-threaded program that has been
-instrumented to save traces of its API calls in a log. 
+Simulate a program where two threads write to the same log file.
+Investigate synchronization to ensure that only one thread at a time
+can write to the log.
 
-Instead of simply calling the API functions, each thread instead calls
-the *tracecapture* function, which calls the API function but also
-saves the call (with arguments) and return (with return value) in the
-trace log.  The tracecapture function uses a lock:
+States where both threads may write to the log are considered unsafe
+states.  Log messages that may have been corrupted by unsynchronized
+writes from both threads are marked.
+
+The simulated multi-threaded program has been instrumented to save
+traces of its API calls in a log.  Instead of simply calling the API
+functions, each thread instead calls the *tracecapture* function,
+which calls the API function but also saves the call (with arguments)
+and return (with return value) in the trace log.  The tracecapture
+function uses a lock:
 
     tracelock = lock()
 
@@ -35,6 +42,9 @@ def tracecapture(thread_id, call, args): # call is action name
 call ids (action ids) for each thread, first index is thread id,
 second index is thread pc.
 
+unsynchronized: set False to use tracelock, True to ignore tracelock
+
+
 State:
 
 pc: program counter for each thread, indexed by thread_id
