edu.mit.ai.psg.traveler
Interface TraceRecorder

All Known Implementing Classes:

TraceRecorderDefault

public interface 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. Principle: if used so that all records are created by the TraceRecorder, provides modularity for changing the recording mechanism without changing the traced program (e.g., see Trace). Currently Traveler comes with two implementations: TraceRecorderDefault and TraceRecorderObservable. (Based in part on "Traveler: the Apiary Observatory", ECOOP'1987). Message Passing: Method received(java.lang.Object, java.lang.reflect.Member, java.lang.Object[]) is for callees to record call invocation; if callee method is synchronized, received(java.lang.Object, java.lang.reflect.Member, java.lang.Object[]) must be called while synchronization is held so that arrival order is recorded correctly. It creates a CallRecord, links it into records via entering(edu.mit.ai.psg.traveler.ActivityRecord) or enteredSynchronization(edu.mit.ai.psg.traveler.SynchronizationRecord), and returns it. Method invoking(java.lang.Object, java.lang.reflect.Member, java.lang.Object[]) is for callers to record call invocation (e.g., calls to native methods). Methods throwing(edu.mit.ai.psg.traveler.CallRecord, java.lang.Throwable), returningVoid(edu.mit.ai.psg.traveler.CallRecord), and returning(edu.mit.ai.psg.traveler.CallRecord, java.lang.Object) keep the call record stack current via exitting(edu.mit.ai.psg.traveler.ActivityRecord), and complete the call record by adding the result information. Blocks: Method beginning(java.lang.String) starts a record for an activity described by a string. Method doing(java.lang.String) starts and exits such an activity (like a print statement). Method beganSynchronization(java.lang.Object, java.lang.reflect.Member) starts an activity for a synchronization region. Access: Method getCurrentRecord() returns the current record for the current thread. Method getBiography(java.lang.Object) returns a list of records of synchronization entries and exits on an object.

See Also:

Trace, TraceRecorderObservable

Method Summary

void	addEntryToBiography(SynchronizationRecord record) add record to biography of target of synchronization
void	addExitToBiography(SynchronizationRecord record) add record to biography of target of synchronization
SynchronizationRecord	beganSynchronization(Object target, Member inMember) Creates and links a record for a synchronized region.
ActivityRecord	beginning(String string) Creates and links a record for an activity (e.g., a block) described by string.
void	clearBiographies() clear all biographies
void	clearBiography(Object target) clear biography of target.
ActivityRecord	doing(ActivityRecord record) convenience function for entering followed immediately by exitting
ActivityRecord	doing(String string) Convenience function for beginning followed immedately by exitting.
SynchronizationRecord	enteredSynchronization(SynchronizationRecord record) If record is not the current activity, call entering(record).
ActivityRecord	entering(ActivityRecord record) Link record to parent activity within thread, and makes record the current activity.
ActivityRecord	exitting(ActivityRecord record) make parent of record, if any, the current record.
List	getBiography(Object target) return a List of activities recorded for this target, e.g., traced calls on synchronized methods
ActivityRecord	getCurrentRecord() get top record on activity stack; may be inherited from thread which created the current thread.
SynchronizationRecord	getSynchronizationHolder(Object target) return entry record of activity currently holding synchronization on target or null if none.
ActivityRecord	getThreadOutermostRecord() get bottom record on activity stack which is specific to this thread, or null.
CallRecord	invoking(Object target, Member member, Object[] parameters) For recording a call from caller: Should be followed by call to returningVoid(edu.mit.ai.psg.traveler.CallRecord), returning(edu.mit.ai.psg.traveler.CallRecord, java.lang.Object), or throwing(edu.mit.ai.psg.traveler.CallRecord, java.lang.Throwable) to record completion of call.
CallRecord	received(Object target, Member member, Object[] parameters) For recording a call from callee: Should be followed by call to returningVoid(edu.mit.ai.psg.traveler.CallRecord), returning(edu.mit.ai.psg.traveler.CallRecord, java.lang.Object), or throwing(edu.mit.ai.psg.traveler.CallRecord, java.lang.Throwable) to record completion of call.
Object	returning(CallRecord record, Object value) Record value in record, and make record parent current activity in this thread (see exitting(edu.mit.ai.psg.traveler.ActivityRecord))
void	returningVoid(CallRecord record) record completion, and make record parent current activity in this thread (see exitting(edu.mit.ai.psg.traveler.ActivityRecord))
Throwable	throwing(CallRecord record, Throwable thrown) Record thrown in record, and make record parent current activity in this thread (see exitting(edu.mit.ai.psg.traveler.ActivityRecord))

Method Detail

received

public CallRecord received(Object target,
                           Member member,
                           Object[] parameters)

For recording a call from callee: Should be followed by call to returningVoid(edu.mit.ai.psg.traveler.CallRecord), returning(edu.mit.ai.psg.traveler.CallRecord, java.lang.Object), or throwing(edu.mit.ai.psg.traveler.CallRecord, java.lang.Throwable) to record completion of call. Creates a CallRecord recording the invocation, makes record the current record, returning record. If callRecord.SynchronizationRecord.isSynchronized()() (i.e., member is synchronized), calls enteredSynchronization(edu.mit.ai.psg.traveler.SynchronizationRecord), else calls entering(edu.mit.ai.psg.traveler.ActivityRecord).

Parameters:

target - target of invocation, or null for static methods and constructors. If target is Cloneable, record will contain a clone of target, preserving its state at time of recording.

member - member invoked, Method or Constructor

parameters - array of actual parameters.

Returns:

record.

invoking

public CallRecord invoking(Object target,
                           Member member,
                           Object[] parameters)

For recording a call from caller: Should be followed by call to returningVoid(edu.mit.ai.psg.traveler.CallRecord), returning(edu.mit.ai.psg.traveler.CallRecord, java.lang.Object), or throwing(edu.mit.ai.psg.traveler.CallRecord, java.lang.Throwable) to record completion of call. Creates a CallRecord recording the invocation, makes record the current record, returning record. If callRecord.SynchronizationRecord.isSynchronizedWait()(), calls enteredSynchronization(edu.mit.ai.psg.traveler.SynchronizationRecord), else calls entering(edu.mit.ai.psg.traveler.ActivityRecord).

Parameters:

target - target of invocation, or null for static methods and constructors. If target is Cloneable, record will contain a clone of target, preserving its state at time of call.

member - member invoked, Method or Constructor

parameters - array of actual parameters.

Returns:

record.

returningVoid

public void returningVoid(CallRecord record)

record completion, and make record parent current activity in this thread (see exitting(edu.mit.ai.psg.traveler.ActivityRecord))

returning

public Object returning(CallRecord record,
                        Object value)

Record value in record, and make record parent current activity in this thread (see exitting(edu.mit.ai.psg.traveler.ActivityRecord))

throwing

public Throwable throwing(CallRecord record,
                          Throwable thrown)

Record thrown in record, and make record parent current activity in this thread (see exitting(edu.mit.ai.psg.traveler.ActivityRecord))

beginning

public ActivityRecord beginning(String string)

Creates and links a record for an activity (e.g., a block) described by string. Ended by exitting(edu.mit.ai.psg.traveler.ActivityRecord)(record).

doing

public ActivityRecord doing(String string)

Convenience function for beginning followed immedately by exitting. May be used to add strings to annotate record (like using print statements), e.g., to describe activities with no internal structure.

beganSynchronization

public SynchronizationRecord beganSynchronization(Object target,
                                                  Member inMember)

Creates and links a record for a synchronized region. Must be called from within the synchronized region to ensure the correct ordering in target's biography. Ended by exitting(edu.mit.ai.psg.traveler.ActivityRecord)(record).

Parameters:

target - target of synchronization (e.g., locked object).

inMember - Method or Constructor in which block is found (used for identifying record in its print string), or null if in a class initializer

entering

public ActivityRecord entering(ActivityRecord record)

Link record to parent activity within thread, and makes record the current activity. Should be followed by call to exitting(edu.mit.ai.psg.traveler.ActivityRecord) at end of activity.

enteredSynchronization

public SynchronizationRecord enteredSynchronization(SynchronizationRecord record)

If record is not the current activity, call entering(record). Add record to biography of record.SynchronizationRecord.getTargetNow()(). Must be called while activity holds synchronization lock (otherwise record may not be added to biography in actual synchronization order).

Throws:

IllegalArgumentException - if not record.SynchronizationRecord.isSynchronized()().

exitting

public ActivityRecord exitting(ActivityRecord record)

make parent of record, if any, the current record. If (record instanceof SynchronizationRecord && (record.SynchronizationRecord.isSynchronized()() || record.SynchronizationRecord.isSynchronizedWait()())) create exit record and add to biography. (Also exit any child record that haven't been exited.)

doing

public ActivityRecord doing(ActivityRecord record)

convenience function for entering followed immediately by exitting

getCurrentRecord

public ActivityRecord getCurrentRecord()

get top record on activity stack; may be inherited from thread which created the current thread.

getThreadOutermostRecord

public ActivityRecord getThreadOutermostRecord()

get bottom record on activity stack which is specific to this thread, or null.

clearBiographies

public void clearBiographies()

clear all biographies

clearBiography

public void clearBiography(Object target)

clear biography of target. May be useful to shorten display. Permits records in biography which are not linked to any other records (e.g., in other biographies or in current threads) to be garbage collected.

getBiography

public List getBiography(Object target)

return a List of activities recorded for this target, e.g., traced calls on synchronized methods

getSynchronizationHolder

public SynchronizationRecord getSynchronizationHolder(Object target)

return entry record of activity currently holding synchronization on target or null if none. If nested, this will be the innermost record, and enclosing records will be available thru ActivityRecord.getParent().

addEntryToBiography

public void addEntryToBiography(SynchronizationRecord record)

add record to biography of target of synchronization

Returns:

record

addExitToBiography

public void addExitToBiography(SynchronizationRecord record)

add record to biography of target of synchronization

Returns:

record