Overview | Package | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD