NCSAHabanero

[ Previous ] [ Index ] [ Next ]

-------------------------------------------------------------------
How to prevent events from clashing with each other
-------------------------------------------------------------------

Limit Arbitrator

Background Information

The Limit Arbitrator is an arbitrator that implements locking. Locking allows a participant to prevent other participants from sending specific events. For example, in a drawing program, if one user grabs a box and starts moving it, that hablet can set a lock on that box, so that other participants cannot also grab that object at that time.

How does this work?

There are three major steps to using the Limit Arbitrator.
  1. Tell Habanero you want to use the Limit Arbitrator.
  2. Make a new Lock.
  3. Use the Lock you made in your hablet.

1. Tell Habanero you want to use the Limit Arbitrator

The tools file you create when installing a new hablet specifies what arbitrator to use. Put this line in the tools file:

2. Make a new Lock

  1. Subclass Lock

    2.  
  2. Override these public methods, if you do not want their default behavior:
    3. public boolean blocks (Action act)
    Should it allow this action if you don't have a key to this lock? The default returns false.

     
    public boolean releaseAfterUsing()
    If this function returns true, then the lock will be automatically released as soon as you use it. The default returns false.

     
    public boolean keyWorksWith (Lock ldRequest)
    If the new lock requested will not work with this lock's key, then this will return false. The default returns true.
     
  3. Implement these abstract methods:
    4. abstract public boolean allows(Action act);
    When you have a key to the lock, should it allow this action?
    abstract public boolean consistent(Lock lkdRequest);
    When you don't have a key to this lock, should it allow the new lock?
To do: add some sort of example here.

3. Use the Lock you made in your hablet.

To use a lock, first get a handle on the arbitrator, then ask the arbitrator for the lock. To do this, ask the MirrorFrame in StartInFrame for its Collobject, and then ask the collobject for its arbitrator.

For example: 
transient private Collobject collobject = null;  
 transient private Arbitrator arbitrator = null;  

 public void startInFrame(MirrorFrame f)   
 {  
   // other code  
   
   collobject = f.getCollobject();  
   arbitrator = collobject.arbitrator();  

   // other code  
 }
Now that you have the arbitrator, you can ask it for a new lock using getLock().

For example:
Key myKey = arbitrator.getLock(new MyLock());
 
Then, you can make your request to do the action corresponding to that lock:
KeyedActionRequest req = 
  new KeyedActionRequest(some_action, collobject, myKey); 
if (!req.requestGranted()) arbitrator.releaseLock(myKey); 
 
Note how it releases the lock if the request isn't granted as well.  When you are done with the lock, this releaseLock() is also how you get rid of it, unless you make it automatic with releaseAfterUsing().

What next?

Read about arbitrators in general.

Learn how to create your own arbitrators. [Not yet written]

Habanero® is a registered trademark owned by The Board of Trustees of the University of Illinois. Copyright 1996-1998. All rights reserved.   Java(TM) is a proprietary trademark owned by Sun Microsystems, Inc.
NCSA
The National Center for Supercomputing Applications
University of Illinois at Urbana-Champaign

Contacts page