de.grogra.util
Interface Lockable

All Known Subinterfaces:

Graph

All Known Implementing Classes:

AttributeOverwritingFilter, GraphBase, GraphFilter, GraphManager, LockableImpl, PersistenceManager

public interface Lockable

An instance of Lockable is a resource on which read- or write-locked tasks can be performed. Several read-locked tasks may be executed concurrently, while only a single write-locked task may be executed at the same time. A write-locked task excludes the concurrent execution of both read- and write-locked tasks, so a write lock is an exclusive lock.

Locks are re-entrant: A task which is executed using a lock may execute further nested, locked tasks in the same thread.

Tasks which should be executed using a lock are specified by implementations of LockProtectedRunnable. The lock/unlock operations are performed implicitly before and after invocation of the method run in LockProtectedRunnable. However, a task may invoke Lock.retain() on its lock in order to suppress the unlock operation after the task has completed: In this case, the lock may be kept for a while and even passed to another thread until it is eventually passed to one of the execute methods of Lockable.

Author:

Ole Kniemeyer

Nested Class Summary

static class

Lockable.DeadLockException An instance of DeadLockException is thrown by executeForcedly(LockProtectedRunnable, boolean) if the operation would result in a dead-lock condition.

Method Summary

void	execute(LockProtectedRunnable task, boolean write) Asynchronously executes a task such that it possesses a lock on this Lockable.
void	execute(LockProtectedRunnable task, Lock retained) Asynchronously executes a task using a lock which has been retained before within another task.
void	executeForcedly(LockProtectedRunnable task, boolean write) Synchronously executes a task such that it possesses a lock on this Lockable.
void	executeForcedly(LockProtectedRunnable task, Lock retained) Synchronously executes a task using a lock which has been retained before within another task.
long	getMaxWaitingTime() Returns the waiting time of the pending task which is waiting longest, or -1 if there is no pending task.
int	getQueueLength() Returns the current number of tasks which are waiting for locked execution.
boolean	isLocked(boolean write) Determines if the current thread has a lock for this Lockable.

Method Detail

execute

void execute(LockProtectedRunnable task,
             boolean write)

Asynchronously executes a task such that it possesses a lock on this Lockable. Note that the execution is asynchronous, so that the thread in which the task will actually be executed may differ from the current thread.

Parameters:

task - the task to execute

write - shall a write lock be obtained?

execute

void execute(LockProtectedRunnable task,
             Lock retained)

Asynchronously executes a task using a lock which has been retained before within another task. Note that the execution is asynchronous, so that the thread in which the task will actually be executed may differ from the current thread.

Parameters:

task - the task to execute

retained - the previously retained lock

See Also:

Lock.retain()

executeForcedly

void executeForcedly(LockProtectedRunnable task,
                     boolean write)
                     throws java.lang.InterruptedException,
                            Lockable.DeadLockException

Synchronously executes a task such that it possesses a lock on this Lockable. The execution is performed in the current thread.

Parameters:

task - the task to execute

write - shall a write lock be obtained?

Throws:

java.lang.InterruptedException

Lockable.DeadLockException

executeForcedly

void executeForcedly(LockProtectedRunnable task,
                     Lock retained)
                     throws java.lang.InterruptedException

Synchronously executes a task using a lock which has been retained before within another task. The execution is performed in the current thread.

Parameters:

task - the task to execute

retained - the previously retained lock

Throws:

java.lang.InterruptedException

See Also:

Lock.retain()

getMaxWaitingTime

long getMaxWaitingTime()

Returns the waiting time of the pending task which is waiting longest, or -1 if there is no pending task.

Returns:

current maximum waiting time of pending tasks

getQueueLength

int getQueueLength()

Returns the current number of tasks which are waiting for locked execution.

Returns:

current number of waiting tasks

isLocked

boolean isLocked(boolean write)

Determines if the current thread has a lock for this Lockable.

Parameters:

write - check for write locks only (true) or for both read and write locks (false)

Returns:

true if the current thread has a lock