tribble.io
Interface Lock

All Known Implementing Classes:
LockFile

public interface Lock

Primitive lock interface. Implements an exclusive locking mechanism.

This interface is designed to provide a means for programs to maintain a lock across multiple method calls (which cannot be done using normal synchronized methods). It may also be used to implement locks that can be shared between multiple programs.

Classes that implement this interface should implement recursive (or nesting) locks, such that calling acquire() more than once results in an internal lock count to be incremented, so that exactly the same number of calls to release() are needed in order to completely release the lock. This parallels the way synchronized objects operate in Java.

Since:
2006-08-01
Version:
$Revision: 1.1 $ $Date: 2006/08/02 03:05:21 $
Author:
David R. Tribble (david@tribble.com).
Copyright 2006 by David R. Tribble, all rights reserved.
Permission is granted to freely use and distribute this source code provided that the original copyright and authorship notices remain intact.

Field Summary
static java.lang.String REV
          Revision information.
 
Method Summary
 boolean acquire(int timeOut)
          Acquire an exclusive lock on this lock object.
 boolean isLocked()
          Determines if this lock has been acquired.
 int lockCount()
          Determines the number of nested locks acquired for this lock.
 boolean release()
          Release the exclusive lock acquired on this lock object.
 

Field Detail

REV

static final java.lang.String REV
Revision information.

See Also:
Constant Field Values
Method Detail

acquire

boolean acquire(int timeOut)
                throws java.io.IOException
Acquire an exclusive lock on this lock object. If the lock has already been acquired, an internal counter is incremented, allowing for recursive (nested) locks.

Parameters:
timeOut - The maximum number of milliseconds to wait while attempting to acquire a lock before giving up. A value of zero specifies an unlimited wait time. Note that the resolution of the system clock may be coarser than one millisecond, so this parameter is only an approximation of the actual time-out interval used.
Returns:
True if an exclusive lock was successfully acquired, otherwise false to indicate that the time-out interval expired before a lock could be acquired.
Throws:
java.io.IOException - Thrown if an I/O error occurs.
Since:
1.1, 2006-08-01

release

boolean release()
                throws java.io.IOException
Release the exclusive lock acquired on this lock object. If the lock has been acquired more than once, an internal lock count is decremented, allowing for recursive (nested) locking. Only when the count becomes zero is the lock actually released.

Returns:
True if the lock was actually released, i.e., if the lock count becomes zero.
Throws:
java.io.IOException - Thrown if an I/O error occurs.
Since:
1.1, 2006-08-01

isLocked

boolean isLocked()
Determines if this lock has been acquired.

Returns:
True if this lock is currently acquired, otherwise false.
Since:
1.1, 2006-08-01

lockCount

int lockCount()
Determines the number of nested locks acquired for this lock.

Returns:
The number of active locks acquired on this lock, or zero if there are none.
Since:
1.1, 2006-08-01