org.openmdx.base.concurrent.locks.jre.before1_5
Class SimpleLock

java.lang.Object
  org.openmdx.base.concurrent.locks.jre.before1_5.SimpleLock

All Implemented Interfaces:

Lock

public class SimpleLock
extends Object
implements Lock

openMDX' Simple Lock Implementaton relies on its Java synchronization methods.

You must not

• use it as argument of a synchronize statement
• invoke any of its wait() methods
• invoke its notify() method
• invoke its notifyAll() method

Constructor Summary

SimpleLock()

Method Summary

void	lock() Acquires the lock.
void	lockInterruptibly() Acquires the lock unless the current thread is interrupted.
Condition	newCondition() Returns a new Condition instance that is bound to this Lock instance.
boolean	tryLock() Acquires the lock only if it is free at the time of invocation.
boolean	tryLock(long time, TimeUnit unit) Acquires the lock if it is free within the given waiting time and the current thread has not been interrupted.
void	unlock() Releases the lock.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleLock

public SimpleLock()

Method Detail

lock

public void lock()

Description copied from interface: Lock

Acquires the lock.

If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

Implementation Considerations

A Lock implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that Lock implementation.

Specified by:

lock in interface Lock

lockInterruptibly

public void lockInterruptibly()
                       throws InterruptedException

Description copied from interface: Lock

Acquires the lock unless the current thread is interrupted.

Acquires the lock if it is available and returns immediately.

If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

• The lock is acquired by the current thread; or
• Some other thread interrupts the current thread, and interruption of lock acquisition is supported.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while acquiring the lock, and interruption of lock acquisition is supported,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

Implementation Considerations

The ability to interrupt a lock acquisition in some implementations may not be possible, and if possible may be an expensive operation. The programmer should be aware that this may be the case. An implementation should document when this is the case.

An implementation can favor responding to an interrupt over normal method return.

A Lock implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that Lock implementation.

Specified by:

lockInterruptibly in interface Lock

Throws:

InterruptedException - if the current thread is interrupted while acquiring the lock (and interruption of lock acquisition is supported).

See Also:

Thread.interrupt()

newCondition

public Condition newCondition()

Description copied from interface: Lock

Returns a new Condition instance that is bound to this Lock instance.

Before waiting on the condition the lock must be held by the current thread. A call to Condition.await() will atomically release the lock before waiting and re-acquire the lock before the wait returns.

Implementation Considerations

The exact operation of the Condition instance depends on the Lock implementation and must be documented by that implementation.

Specified by:

newCondition in interface Lock

Returns:

A new Condition instance for this Lock instance.

tryLock

public boolean tryLock()

Description copied from interface: Lock

Acquires the lock only if it is free at the time of invocation.

Acquires the lock if it is available and returns immediately with the value true. If the lock is not available then this method will return immediately with the value false.

A typical usage idiom for this method would be:

      Lock lock = ...;
      if (lock.tryLock()) {
          try {
              // manipulate protected state
          } finally {
              lock.unlock();
          }
      } else {
          // perform alternative actions
      }
 

This usage ensures that the lock is unlocked if it was acquired, and doesn't try to unlock if the lock was not acquired.

Specified by:

tryLock in interface Lock

Returns:

true if the lock was acquired and false otherwise.

tryLock

public boolean tryLock(long time,
                       TimeUnit unit)
                throws InterruptedException

Description copied from interface: Lock

Acquires the lock if it is free within the given waiting time and the current thread has not been interrupted.

If the lock is available this method returns immediately with the value true. If the lock is not available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

• The lock is acquired by the current thread; or
• Some other thread interrupts the current thread, and interruption of lock acquisition is supported; or
• The specified waiting time elapses

If the lock is acquired then the value true is returned.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while acquiring the lock, and interruption of lock acquisition is supported,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all.

Implementation Considerations

The ability to interrupt a lock acquisition in some implementations may not be possible, and if possible may be an expensive operation. The programmer should be aware that this may be the case. An implementation should document when this is the case.

An implementation can favor responding to an interrupt over normal method return, or reporting a timeout.

A Lock implementation may be able to detect erroneous use of the lock, such as an invocation that would cause deadlock, and may throw an (unchecked) exception in such circumstances. The circumstances and the exception type must be documented by that Lock implementation.

Specified by:

tryLock in interface Lock

Parameters:

time - the maximum time to wait for the lock

unit - the time unit of the time argument.

Returns:

true if the lock was acquired and false if the waiting time elapsed before the lock was acquired.

Throws:

InterruptedException - if the current thread is interrupted while acquiring the lock (and interruption of lock acquisition is supported).

See Also:

Thread.interrupt()

unlock

public void unlock()

Description copied from interface: Lock

Releases the lock.

Implementation Considerations

A Lock implementation will usually impose restrictions on which thread can release a lock (typically only the holder of the lock can release it) and may throw an (unchecked) exception if the restriction is violated. Any restrictions and the exception type must be documented by that Lock implementation.

Specified by:

unlock in interface Lock