com.webobjects.foundation
Class NSLock

java.lang.Object
  |
  +--com.webobjects.foundation.NSLock

All Implemented Interfaces:

NSLocking

public class NSLock

extends Object

implements NSLocking

An NSLock object is used to coordinate the operation of multiple threads of execution within the same application. An NSLock object can be used to mediate access to an application's global data or to protect a critical section of code, allowing it to run atomically.

An NSLock object represents a lock that can be acquired by only a single thread at a time. While one thread holds the lock, any other thread is prevented from doing so until the owner relinquishes the lock. An application can have multiple NSLock objects, each protecting different sections of code. It's safest to create all of the locks before the application becomes multi-threaded, to avoid race conditions. To create additional locks after the application becomes multi-threaded, the new lock must be made inside a critical code section that is itself protected by an existing lock.

The basic interface to NSLock is declared by the NSLocking interface, which defines the lock and unlock methods. To this base, NSLock adds the tryLock methods. Whereas the lock method declared in the interface doesn't return until it is successful, the methods declared in this class add more flexible means of acquiring a lock.

An NSLock could be used to coordinate the updating of a visual display shared by a number of threads involved in a single calculation:

 boolean moreToDo =true;
 NSLock myLock =new NSLock();
 ...
 while (moreToDo){
   //Do another increment of calculation
   //until there is no more to do.
   if (myLock.tryLock()){
     //Update display used by all threads.
     myLock.unlock();
   }
 }
 

The NSLock, NSMultiReaderLock, and NSRecursiveLock classes all adopt the NSLocking interface and offer various additional features and performance characteristics.

See Also:

tryLock(), NSLocking.lock(), NSLocking.unlock(), NSLocking

Field Summary

Fields inherited from interface com.webobjects.foundation.NSLocking

OneCentury, OneDay, OneHour, OneMinute, OneSecond, OneWeek, OneYear

Constructor Summary

NSLock()
Creates an NSLock object.

Method Summary

void	lock() Conformance to NSLocking.
boolean	lockBeforeDate(NSTimestamp timestamp) Deprecated.
String	toString()
boolean	tryLock() Attempts to acquire a lock.
boolean	tryLock(long msecs) Attempts to acquire a lock for msec milliseconds.
boolean	tryLock(NSTimestamp timestamp) Attempts to acquire a lock until the time specified by timestamp.
void	unlock() Conformance to NSLocking.

Methods inherited from class java.lang.Object

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

Constructor Detail

NSLock

public NSLock()

Creates an NSLock object.

Method Detail

lock

public void lock()

Conformance to NSLocking.

Specified by:

lock in interface NSLocking

lockBeforeDate

public boolean lockBeforeDate(NSTimestamp timestamp)

Deprecated.

Use tryLock(NSTimestamp timestamp) instead.

See Also:

tryLock()

toString

public String toString()

Overrides:

toString in class Object

Returns:

a string representation of the receiver indicating whether or not the lock is taken

tryLock

public boolean tryLock()

Attempts to acquire a lock.

Returns:

immediately, with a value of true if successful and false otherwise

tryLock

public boolean tryLock(long msecs)

Attempts to acquire a lock for msec milliseconds. The thread is blocked until the receiver acquires the lock or msec milliseconds have passed.

Parameters:

msecs - time for which the lock to be taken

Returns:

true if the lock is acquired within msec, or false if the time limit expires before a lock can be acquired

tryLock

public boolean tryLock(NSTimestamp timestamp)

Attempts to acquire a lock until the time specified by timestamp. The thread is blocked until the receiver acquires the lock or timestamp is reached.

Parameters:

timestamp - the specified time before which the lock is to be taken

Returns:

true if the lock is acquired within msec, or false if the time limit expires before a lock can be acquired.

unlock

public void unlock()

Conformance to NSLocking. See the method description of unlock in the interface specification for NSLocking.

Specified by:

unlock in interface NSLocking