coordination
Class Coordinator

java.lang.Object
  |
  +--coordination.Coordinator
Direct Known Subclasses:
GameCoordinator, RegistryCoordinator

public abstract class Coordinator
extends java.lang.Object

The Coordinator class provides the basic functionality for synchronizing and coordinating different threads upon entering and exiting methods. It can be used in two different ways: 1) by instantiating regular coordinator objects that are used by aspects; or 2) by extending it (sub-classing) with coordinator aspects.

Method invocations are the smallest units for defining critical sections and pre-conditions. The use of coordinators, either regular objects or aspect instances, should always end up by invoking guardedEntry(...) in a before weave and guardedExit(...) in an after weave for all methods that need coordination. guardedEntry and guardedExit are the methods that actually manage the synchronization and coordination constraints given by their parameters and by pre-existent exclusion markers.

The synchronization of threads for the execution of critical section methods in an object is done by marking those methods as self- and/or mutually-exclusive (addSelfex, addMutex). Just by itself, addSelfex("M") does not enforce the self-exclusion of method M - enforcement is done by invoking guardedEntry before M is executed. Similarly, addMutex(new String[] {"M1", "M2"}) does not enforce the mutual exclusion between methods M1 and M2.

A guardedEntry on a method that has been marked as self-exclusive ensures that the method is executed in the invoked object by only one thread at a time. A guardedEntry on a method that has been marked has mutually- exclusive with other methods ensures that the execution of that method by a thread in the invoked object temporarily blocks the execution by other threads of the methods that are in the same mutex set.

The coordination of threads, i.e. their explicit suspension and resumption, is done through the use of pre-conditions and coordination actions that are passed as parameters to guardedEntry and guardedExit with the form of anonymous classes.


Advice Summary
advice coordinatorCut()
before()
 
 affects: spacewar.Game, spacewar.Registry
advice coordinatorCut()
after()
 
 affects: spacewar.Game, spacewar.Registry

 
Crosscut Summary
coordinatorCut()
 

 
Constructor Summary
Coordinator()
          
 
Method Summary
 void addMutex(java.lang.String[] methNames)
           Takes an array of multi-part method names and marks those methods as mutually exclusive.
 void addSelfex(java.lang.String methName)
           Takes a multi-part method name (eg "BoundedBuffer.put") and marks that method as self-exclusive.
 void guardedEntry(java.lang.String methName)
           This method is the guard for enforcing all synchronization and coordination constraints of a given method, and it should be called just before the method is executed.
 void guardedEntry(java.lang.String methName, Condition condition)
           Just like guardedEntry(String methName), but the given method is executed only when the given condition is true.
 void guardedEntry(java.lang.String methName, Condition condition, CoordinationAction action)
           Just like guardedEntry(String methName), but the given method is executed only when the given condition is true; the additional coordination action that is executed before the given method is executed.
 void guardedEntry(java.lang.String methName, CoordinationAction action)
           Just like guardedEntry(String methName), but with an additional coordination action that is executed before the given method is executed.
 void guardedEntryWithTimeout(java.lang.String methName, Condition condition, CoordinationAction action, long millis)
           This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.
 void guardedEntryWithTimeout(java.lang.String methName, Condition condition, long millis)
           This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.
 void guardedEntryWithTimeout(java.lang.String methName, CoordinationAction action, long millis)
           This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.
 void guardedEntryWithTimeout(java.lang.String methName, long millis)
           This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.
 void guardedExit(java.lang.String methName)
           This method provides the means for updating all synchronization and coordination state after the execution of a given method, and it should be called after the method is executed.
 void guardedExit(java.lang.String methName, CoordinationAction action)
           Just like guardedExit(String methName) but with an additional coordination action that is executed.
 void removeMutex(java.lang.String[] methNames)
           Takes an array of multi-part method names that correspond to an existing mutex set and remove the mutual exclusion constraint.
 void removeSelfex(java.lang.String methName)
           Takes a multi-part method name (e.g.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

 
Advice Detail

advice coordinatorCut()

before()

 affects: spacewar.Game, spacewar.Registry


advice coordinatorCut()

after()

 affects: spacewar.Game, spacewar.Registry

 
Crosscut Detail

coordinatorCut()

Constructor Detail

Coordinator

public Coordinator()
Method Detail

addSelfex

public void addSelfex(java.lang.String methName)
Takes a multi-part method name (eg "BoundedBuffer.put") and marks that method as self-exclusive. No checks are made with respect to the existence of the method whose name is given.

removeSelfex

public void removeSelfex(java.lang.String methName)
Takes a multi-part method name (e.g. "BoundedBuffer.put") and removes that method from the list of self-exclusive methods.

addMutex

public void addMutex(java.lang.String[] methNames)
Takes an array of multi-part method names and marks those methods as mutually exclusive. No checks are made with respect to the existence of the methods whose names are given.

removeMutex

public void removeMutex(java.lang.String[] methNames)
Takes an array of multi-part method names that correspond to an existing mutex set and remove the mutual exclusion constraint. If the given mutex set does not exist, removeMutex does nothing.

guardedEntry

public void guardedEntry(java.lang.String methName)
This method is the guard for enforcing all synchronization and coordination constraints of a given method, and it should be called just before the method is executed. In this form, only the method name is given. The only constraints checked are the exclusion constraints. If the method was previousely marked as selfex (through addSelfex), guardedEntry ensures that the method is executed only when no other thread is executing it. If the method was previousely marked as being in one or more mutex sets, guardedEntry ensures that the method is executed only when no other thread is executing any of the methods with which the give method is mutexed.

guardedEntry

public void guardedEntry(java.lang.String methName,
                         Condition condition)
Just like guardedEntry(String methName), but the given method is executed only when the given condition is true. guardedEntry is the guard for enforcing all synchronization and coordination constraints of a given method, and it should be called just before the method is executed. In this form, the method name is given along with a condition. The constraints checked are the exclusion constraints and whether the given condition is true. If the method was previousely marked as selfex (through addSelfex), guardedEntry ensures that the method is executed only when no other thread is executing it. If the method was previousely marked as being in one or more mutex sets, guardedEntry ensures that the method is executed only when no other thread is executing any of the methods with which the give method is mutexed. If the condition is false, guardedEntry suspends the current thread. That thread remains suspended until the condition becomes true, in which case all constraints are rechecked before the method is executed. When all exclusion constraints are checked and the given condition is true, the given method is executed.

guardedEntry

public void guardedEntry(java.lang.String methName,
                         CoordinationAction action)
Just like guardedEntry(String methName), but with an additional coordination action that is executed before the given method is executed. guardedEntry is the guard for enforcing all synchronization and coordination constraints of a given method, and it should be called just before the method is executed. In this form, the method name is given along with a coordination action. The only constraints checked are the exclusion constraints. If the method was previousely marked as selfex (through addSelfex), guardedEntry ensures that the method is executed only when no other thread is executing it. If the method was previousely marked as being in one or more mutex sets, guardedEntry ensures that the method is executed only when no other thread is executing any of the methods with which the give method is mutexed. The given coordination action is executed just before the given method is executed.

guardedEntry

public void guardedEntry(java.lang.String methName,
                         Condition condition,
                         CoordinationAction action)
Just like guardedEntry(String methName), but the given method is executed only when the given condition is true; the additional coordination action that is executed before the given method is executed. guardedEntry is the guard for enforcing all synchronization and coordination constraints of a given method, and it should be called just before the method is executed. In this form, the method name is given along with a condition and a coordination action. The constraints checked are the exclusion constraints and whether the given condition is true. If the method was previousely marked as selfex (through addSelfex), guardedEntry ensures that the method is executed only when no other thread is executing it. If the method was previousely marked as being in one or more mutex sets, guardedEntry ensures that the method is executed only when no other thread is executing any of the methods with which the give method is mutexed. If the condition is false, guardedEntry suspends the current thread. That thread remains suspended until the condition becomes true, in which case all constraints are rechecked before the method is executed. When all exclusion constraints are checked and the given condition is true, the given method is executed. The given coordination action is executed just before the given method is executed.

guardedEntryWithTimeout

public void guardedEntryWithTimeout(java.lang.String methName,
                                    long millis)
                             throws TimeoutException
This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.

guardedEntryWithTimeout

public void guardedEntryWithTimeout(java.lang.String methName,
                                    Condition condition,
                                    long millis)
                             throws TimeoutException
This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.

guardedEntryWithTimeout

public void guardedEntryWithTimeout(java.lang.String methName,
                                    CoordinationAction action,
                                    long millis)
                             throws TimeoutException
This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.

guardedEntryWithTimeout

public void guardedEntryWithTimeout(java.lang.String methName,
                                    Condition condition,
                                    CoordinationAction action,
                                    long millis)
                             throws TimeoutException
This method is similar to guardedEntry, but it takes an additional parameter - the milliseconds after which any suspension will abort with a timeout.

guardedExit

public void guardedExit(java.lang.String methName)
This method provides the means for updating all synchronization and coordination state after the execution of a given method, and it should be called after the method is executed. In this form, only the method name is given. The synchronization state for self- and mutual-exclusion is automatically upadted.

guardedExit

public void guardedExit(java.lang.String methName,
                        CoordinationAction action)
Just like guardedExit(String methName) but with an additional coordination action that is executed. guardedExit provides the means for updating all synchronization and coordination state after the execution of a given method, and it should be called after the method is executed. In this form, the method name is given along with a coordination action. The synchronization state for self- and mutual-exclusion is automatically upadted. The given coordination action is executed.