|
|
|
|
org.eclipse.emf.transaction.util
Class Lock
java.lang.Object
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. |
Lock
public Lock()
- Initializes me.
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
-
|
|
|