Package edu.mit.ai.psg.traveler

Traveler provides means to trace/record the history of execution of concurrent programs, and to browse/navigate these records as nested call outlines, i.e., the activation order within threads, and as linear object biographies, i.e., the arrival order of synchronization at objects. Recording history can be particularly important in concurrent programs where nondeterministic scheduling means the arrival order of threads may not always repeat itself on subsequent runs.

See:
Description

Interface Summary

ActivityRecord	Interface for records of hierarchical activities with at most one parent and zero or more child subactivities.
ActivityRecordMethods.Iterator
CallRecord	Activity record interface for method or constructor calls, including both invocation and result (return or throw).
ChangeObserver	Interface for observers.
ObservableBiographyRecorder	ObservableBiographyRecorder -- interface for trace recorders which may be observed adding to biography by ChangeObservers
ObservableRecord	ObservableRecord -- interface for activity records which may be observed by ChangeObservers
ObservableTraceRecorder	ObservableTraceRecorder -- interface for trace recorders which may be observed adding to biography by ChangeObservers
SynchronizationRecord	Activity record interface for synchronization blocks, including method calls.
SynchronizationRecord.Entry	activity record for entering synchronization.
SynchronizationRecord.Exit	activity record for entering synchronization.
TraceRecorder	Interface for trace recording facilities, which provide means to create a tree of nested ActivityRecords for each thread invoking traced methods, and a biography sequencing records of entrances into synchronized activities for each synchronized object.

Class Summary

ActivityRecordBase	Base class for records of hierarchical activities with at most one parent and zero or more child subactivities.
ActivityRecordMethods
ActivityRecordMethods.BiographyIterator	Iterator returned by ActivityRecordMethods.inBiographyIterator(boolean, boolean, boolean, boolean, boolean, edu.mit.ai.psg.traveler.SynchronizationRecord, java.util.List)
ActivityRecordMethods.IteratorBase	Abstract base class for ActivityRecord iterators; derived classes add method to computeNext()
ActivityRecordMethods.SuperactivityIterator	Iterator returned by ActivityRecordMethods.superactivityIterator(boolean, edu.mit.ai.psg.traveler.ActivityRecord, edu.mit.ai.psg.utilities.IUnaryPredicate)
ActivityRecordMethods.ThreadIterator	Iterator returned by ActivityRecordMethods.inThreadIterator(boolean, boolean, boolean, boolean, edu.mit.ai.psg.traveler.ActivityRecord, edu.mit.ai.psg.utilities.IUnaryPredicate, edu.mit.ai.psg.utilities.IUnaryPredicate)
ActivityRecordObservableBase	Base class for records which will be observed.
CallRecordDefault	Default CallRecord used by TraceRecorderDefault.invoking(java.lang.Object, java.lang.reflect.Member, java.lang.Object[]).
CallRecordObservable	Extends CallRecordDefault to support ChangeObservers.
ObservableSupport	Support for observable activity records.
StringRecord	Activity record for inserting a descriptive string into the record, e.g., for human browsing.
StringRecordObservable	Activity record for inserting a descriptive string into the record, e.g., for human browsing.
SynchronizationRecordDefault	Default implementation of SynchronizationRecord.
SynchronizationRecordDefault.Entry	default class for recording entry into synchronization in a biography
SynchronizationRecordDefault.Exit	default class for recording exit from synchronization in a biography
SynchronizationRecordObservable	Extends SynchronizationRecordDefault to support ChangeObservers.
SynchronizedRecordDefault	Trace ActivityRecord for synchronized blocks, to appear in biography of target object.
Trace	Trace recording facility which creates a tree of nested ActivityRecords for each thread invoking traced methods, and a biography sequencing records of entrances into synchronized activities for each synchronized object.
TraceRecorderDefault	TraceRecorderDefault provides a default implementation for TraceRecorder.
TraceRecorderObservable	An alternate trace recorder that produces observable call records and provides means to observe additions to biographies.
TravelerActivityRenderer	TravelerActivityRenderer: displays parent and children of ActivityRecords's for navigating Activity hierarchy.
TravelerBiographyRenderer	TravelerBiographyRenderer: children of object display the chronological history in records of threads gaining exclusive access to the object: synchronized method calls, resynchronizing after wait, etc.
TravelerCallRenderer	Renders call outline to display call trace records produced by Trace: child of call record are nested calls and other nested activities.
TravelerOutliner	Extends Jexa outliner with alternate Renderers for ActivityRecord produced by Trace.
TravelerOutliner.TravelerOutlineMaker

Package edu.mit.ai.psg.traveler Description

Traveler provides means

• to trace/record the history of execution of concurrent programs, and
• to browse/navigate these records
  • as nested call outlines, i.e., the activation order within threads, and
  • as linear object biographies, i.e., the arrival order of synchronization at objects.

Recording history can be particularly important in concurrent programs where nondeterministic scheduling means the arrival order of threads may not always repeat itself on subsequent runs. Traveler "travels across space and back in time" to show what happened.

Trace provides methods to trace (i.e., record) the entering and exiting of activities by threads, particularly (but not only) method and constructor calls, and the synchronization order at objects. Selective or comprehensive records of multithreaded programs can be performed by making the appropriate calls to Trace rather than print statements. The resulting records can be navigated by thread or object, easing the task of reading and relating events in the trace output created by concurrent threads.

Trace does not provide means to cause your program to call its methods. Currently this may be done by either

• running the program using the edu.mit.ai.psg.jeva Java Evaluator using an evalhook (see TraceCallsEvalHook and examples for eval hook), or
• adding specific Trace method calls to the parts of your program you would like to trace, much as you might add print statements (see examples with selective tracing).

(In future development environments, method tracing could automatically be added to and removed from programs in a manner similar to how breakpoints are added and removed. Tracing calls could also be generated by a reflective compiler such as OpenJava, or with the help of a virtual machine such as Metaxa/MetaJava). The methods of Trace invoke the appropriate operations in the current TraceRecorder, so the default trace recorder, TraceRecorderDefault, may be extended or replaced. TraceRecorderDefault can create a hierarchy of ActivityRecords for each thread which invokes traced methods. All activity records record the parent activity and children activities. Activities of threads started by an activity can be included in its child activities. CallRecords are activity records which also record the call invocation target and arguments, and later the result (returned value or thrown exception). A StringRecord can be used to to insert an arbitrary string into the record. TraceRecorderDefault can create a biography recording the synchronization arrival order at an object, i.e., the sequence of traced activities acquiring synchronization at the object. (Java synchronization is acquired by synchronized methods and blocks, and re-acquired by the Object.wait() method. Programs which use higher level synchronization abstractions [e.g., to guarantee first-in, first-out ordering], may use selective tracing with Trace.beganSynchronization(java.lang.Object, java.lang.reflect.Member).) These records (or any other records interfaced through the ActivityRecord and/or CallRecord interfaces) can be viewed as expandable/collapsible edu.mit.ai.psg.ui.outliner:

• TravelerActivityRenderer renders activity records as an outline of child activities,
• TravelerCallRenderer renders call records as an outline of nested invocation-result pairs.
• TravelerBiographyRenderer renders a biography as a sequence of activities/calls.

These renderers also provide pop-up menu commands to go back and forth between these views:

• to show a synchronization event from a thread call outline in context in the synchronization target object's biography.
• to show an event in a biography in context of the invoking threads caller activities.

(Based in part on "Traveler: the Apiary Observatory", ECOOP'1987).