org.eclipse.emf.transaction.internal
Interface ITransactionLock

All Known Implementing Classes:

EmptyLock, Lock

public interface ITransactionLock

Common interface for locks in transactionable editing domains.

Since:

1.4

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.
void	checkedTransfer(Thread thread)
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.
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.

Method Detail

getOwner

Thread getOwner()

Queries the current owner of the lock.

Returns:

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

getDepth

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

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

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

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

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

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

checkedTransfer

void checkedTransfer(Thread thread)