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