org.eclipse.emf.transaction.util
Class Lock

java.lang.Object
  extended by org.eclipse.emf.transaction.util.Lock

public class Lock
extends Object

Implementation of a lock. The lock is recursive; it can be acquired any number of times by the same thread, but it records how many times it was acquired (its depth). It must be released as many times as it was acquired.

If there is a possibility that the thread attempting to acquire a lock may be the Eclipse UI thread, then it is advisable to use the uiSafeAcquire(boolean) method to acquire the lock. This method uses the Eclipse Jobs API to ensure that the UI thread maintains the liveness of the event loop and shows the "Blocked" dialog when necessary to inform the user of what other activities in the resource that it is waiting for.

A lock may be acquired for exclusive or non-exclusive access to the resource that it is protecting. Any thread that holds the lock non-exclusively can yield it to other threads that are waiting for it as long as those threads are trying to acquire it for non-exclusive access. If the yield returns true, then the thread must release it (to whatever depth it currently holds it) so that others may acquire it. While the lock is being yielded, it cannot be acquired for exclusive access.

This lock implementation ensures fairness of awakening threads waiting to acquire it by enqueuing them in FIFO fashion. In addition, if a thread times out of a timed acquire call, it maintains its position in the queue if it re-attempts the acquire before it is dequeued. This helps threads that need to time out regularly (e.g., to check for progress monitor cancellation) to still benefit from the fairness of the scheduling strategy.

The interaction of threads with Lock instances can be debugged by enabling the org.eclipse.emf.transaction/debug/locking trace option.


Nested Class Summary
 class Lock.Access
          A class that grants special Lock manipulation privileges to its subclasses, that it knows as particular friends.
 
Constructor Summary
Lock()
          Initializes me.
 
Method Summary
 void acquire(boolean exclusive)
          Acquires me, waiting as long as necessary or until I am interrupted.
 boolean acquire(long timeout, boolean exclusive)
          Attempts to acquire me, timing out after the specified number of millis.
 int getDepth()
          Queries the depth to which I am acquired by the calling thread.
 Thread getOwner()
          Queries the current owner of the lock.
 void release()
          Releases me.
 String toString()
           
 void uiSafeAcquire(boolean exclusive)
          Attempts to acquire me (without a timeout) in a manner that is safe to execute on the UI thread.
 boolean yield()
          Temporarily yields the lock to another thread that does not require exclusive access, if any such thread exists.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Lock

public Lock()
Initializes me.

Method Detail

getOwner

public Thread getOwner()
Queries the current owner of the lock.

Returns:
the thread that owns me, or null if I am available

getDepth

public int getDepth()
Queries the depth to which I am acquired by the calling thread. This is the number of times the calling thread has acquired me and not yet released. Note that if the calling thread does not own me, I appear to have a depth of zero. Acquiring in this case will wait for the owning thread to finish releasing.

Returns:
my depth

acquire

public void acquire(boolean exclusive)
             throws InterruptedException
Acquires me, waiting as long as necessary or until I am interrupted. if I already own this lock, then its lock depth is increased. That means one more call to release() for me to make.

Note: The current thread must not own my monitor when it calls this method, otherwise it will cause deadlock. Deadlock would be guaranteed because every thread waits on a different object that is not me, so my monitor is not released when the calling thread blocks.

Parameters:
exclusive - true if the current thread needs exclusive access (i.e., no other threads may currently be yielding me); false, otherwise
Throws:
InterruptedException - on interruption of the calling thread

acquire

public boolean acquire(long timeout,
                       boolean exclusive)
                throws InterruptedException
Attempts to acquire me, timing out after the specified number of millis.

Note: The current thread must not own my monitor when it calls this method, otherwise it will cause deadlock. Deadlock would be guaranteed because every thread waits on a different object that is not me, so my monitor is not released when the calling thread blocks.

Parameters:
timeout - the number of milliseconds to wait before giving up on the lock, or 0 to wait as long as necessary
exclusive - true if the current thread needs exclusive access (i.e., no other threads may currently be yielding me); false, otherwise
Returns:
true if the caller successfully acquired me; false if it did not within the timeout
Throws:
IllegalArgumentException - if timeout is negative
InterruptedException - on interruption of the calling thread

uiSafeAcquire

public void uiSafeAcquire(boolean exclusive)
                   throws InterruptedException
Attempts to acquire me (without a timeout) in a manner that is safe to execute on the UI thread. This ensures that, in an Eclipse UI environment, if the UI thread is blocked waiting for me, the Job Manager will show the block dialog to inform the user of what is happening.

If this method is called from a thread that is running as a Job, then it behaves identically to acquire(boolean).

Note: The current thread must not own my monitor when it calls this method, otherwise it will cause deadlock. Deadlock would be guaranteed because every thread waits on a different object that is not me, so my monitor is not released when the calling thread blocks.

Parameters:
exclusive - true if the current thread needs exclusive access (i.e., no other threads may currently be yielding me); false, otherwise
Throws:
InterruptedException - in case of interrupt while waiting or if the user cancels the lock-acquisition job that is blocking the UI thread

release

public void release()
Releases me. Note that my depth may still be positive, in which case I would need to be released again (recursively).

Throws:
IllegalStateException - if the calling thread does not own me

yield

public boolean yield()
Temporarily yields the lock to another thread that does not require exclusive access, if any such thread exists. Note that, if this method returns true, then the caller must actually release me before another thread can take me. It then resumes by acquiring me again, layer.

Returns:
true if the lock was successfully yielded to another thread; false, otherwise

toString

public String toString()
Overrides:
toString in class Object

Copyright 2002, 2007 IBM Corporation and others.
All Rights Reserved.