edu.mit.ai.psg.traveler
Interface SynchronizationRecord

All Known Subinterfaces:

CallRecord

All Known Implementing Classes:

SynchronizationRecordDefault

public interface SynchronizationRecord

extends ActivityRecord

Activity record interface for synchronization blocks, including method calls. Implementing this interface means the record can be used for a synchronized activity; it does not mean that every instance is necessarily a record of a synchronized activity (for example, not all calls are synchronized). Use isSynchronized() and isSynchronizedWait() to test whether an individual record is a record of a synchronized activity. Synchronization activities appear indirectly in the biography of the synchronized (target) object. A synchronized activity may be discontinuous, containing periods where it is waiting while other synchronized activities access the target [e.g., by using java's wait()]. Thus, it is the enter and exit subactivities that appear in chronological ordered in the target's biography. The entry and exit records can be obtained from a synchronized record using getSynchronizationEntry() and getSynchronizationExit() (use getParent() to go from the Entry or Exit to the SynchronizedRecord). Synchronization activities may be nested within a single thread: a synchronized block may call a synchronized method, perhaps indirectly through another method. In such a situation, the target is not released when the inner synchronization activity exits. In addition, wait activities (temporarily) release synchronization letting other threads in, and restore the stack of synchronizing activities when the wait exits. For both these situations, getSynchronizationParent() and getSynchronizationChildren() can be used in addition to the chronological biography to to navigate this hierarchy of synchronization activities. Note that entering and exitting synchronization are activities in their own right, so records of higher level synchronization (e.g., queuing serializers) may be constructed which also show details of the entering or exitting activities. (I.e., this is not restricted to Java's synchronized construct.)

Inner Class Summary

static interface	SynchronizationRecord.Entry activity record for entering synchronization.
static interface	SynchronizationRecord.Exit activity record for entering synchronization.

Method Summary

void	addSynchronizationChild(SynchronizationRecord childRecord) add record of nested/recursive call for synchronization e.g., a nested synchronized block or wait.
SynchronizationRecord.Entry	addSynchronizationEntry() Called by a TraceRecorder when adding entry for this activity to target's biography.
SynchronizationRecord.Exit	addSynchronizationExit() Called by a TraceRecorder when adding exit for this activity to target's biography.
List	getSynchronizationChildren()
SynchronizationRecord.Entry	getSynchronizationEntry() returns record of entering synchronization for this activity.
SynchronizationRecord.Exit	getSynchronizationExit() returns record of exitting synchronization for this activity.
SynchronizationRecord	getSynchronizationParent()
Object	getTargetNow() return current the target of the sychronization as it is now, or null if call invoked a static method or constructor.
Object	getTargetThen() return a clone of target as it was when record was created, or null if target was not cloned.
boolean	isSynchronized() true if activity is synchronized (exclusive on synchronized target).
boolean	isSynchronizedWait() true if activity is temporary release of synchronization (on synchronized target), so exitting activity regains exclusive access to synchronized target, and should also be added to biography.
void	setSynchronizationParent(SynchronizationRecord parentRecord) called by addSynchronizationChild(edu.mit.ai.psg.traveler.SynchronizationRecord)

Methods inherited from interface edu.mit.ai.psg.traveler.ActivityRecord

addChild, addThreadedChild, finished, getChildren, getChildrenInThread, getParent, getThreadedChildren, isFinished, setParent

Method Detail

isSynchronized

public boolean isSynchronized()

true if activity is synchronized (exclusive on synchronized target).

isSynchronizedWait

public boolean isSynchronizedWait()

true if activity is temporary release of synchronization (on synchronized target), so exitting activity regains exclusive access to synchronized target, and should also be added to biography.

See Also:

Object.wait()

getTargetNow

public Object getTargetNow()

return current the target of the sychronization as it is now, or null if call invoked a static method or constructor.

getTargetThen

public Object getTargetThen()

return a clone of target as it was when record was created, or null if target was not cloned.

getSynchronizationEntry

public SynchronizationRecord.Entry getSynchronizationEntry()

returns record of entering synchronization for this activity. returns null if doesn't exist.

getSynchronizationExit

public SynchronizationRecord.Exit getSynchronizationExit()

returns record of exitting synchronization for this activity. returns null if doesn't exist.

addSynchronizationChild

public void addSynchronizationChild(SynchronizationRecord childRecord)

add record of nested/recursive call for synchronization e.g., a nested synchronized block or wait. Calls childRecord.setSynchronizationParent(edu.mit.ai.psg.traveler.SynchronizationRecord)(this)

setSynchronizationParent

public void setSynchronizationParent(SynchronizationRecord parentRecord)

called by addSynchronizationChild(edu.mit.ai.psg.traveler.SynchronizationRecord)

getSynchronizationParent

public SynchronizationRecord getSynchronizationParent()

Returns:

record of enclosing recorded synchronization activity, or null if none. SynchronizationParent may be indirect caller if intermediate activities are not recorded.

getSynchronizationChildren

public List getSynchronizationChildren()

Returns:

list of SynchronizationRecords of recursive synchronization activities during this activity (e.g., recursive java synchronization by a thread).

addSynchronizationEntry

public SynchronizationRecord.Entry addSynchronizationEntry()

Called by a TraceRecorder when adding entry for this activity to target's biography. Initializes, adds, and returns a synchronization entry record for target's biography (entry must be first child of this activity in thread).

Throws:

IllegalStateException - if not isSynchronized() or isSynchronizedWait(), or if this already has an entry.

See Also:

getSynchronizationEntry()

addSynchronizationExit

public SynchronizationRecord.Exit addSynchronizationExit()

Called by a TraceRecorder when adding exit for this activity to target's biography. Initializes, adds, and returns a synchronization exit record for target's biography (exit must be last child in thread).

Throws:

IllegalStateException - if not isSynchronized() or isSynchronizedWait(), or if this already has an exit.

See Also:

getSynchronizationExit()