PATH Documentation > WebObjects

Table of Contents

NSLocking


Package:
com.webobjects.foundation

Interface Description


The NSLocking protocol declares the elementary methods adopted by classes that define lock objects. A lock object is used to coordinate the actions of multiple threads of execution within a single application. By using a lock object, an application can protect critical sections of code from being executed simultaneously by separate threads, thus protecting shared data and other shared resources from corruption.

For example, consider a multithreaded application in which each thread updates a shared counter. If two threads simultaneously fetch the current value into local storage, increment it, and then write the value back, the counter will be incremented only once, losing one thread's contribution. However, if the code that manipulates the shared data (the critical section of code) must be locked before being executed, only one thread at a time can perform the updating operation, and collisions are prevented.

A lock object is either locked or unlocked. You acquire a lock by sending the object a lock message, thus putting the object in the locked state. You relinquish a lock by sending an unlock message, and thus putting the object in the unlocked state. (The Foundation classes that adopt this protocol define additional ways to acquire and relinquish locks.)

The lock method as declared in this protocol is blocking. That is, the thread that sends a lock message is blocked from further execution until the lock is acquired (presumably because some other thread relinquishes its lock). Classes that adopt this protocol typically add methods that offer nonblocking alternatives.

These Foundation classes conform to the NSLocking protocol:


Class Adds these features to the basic protocol
NSLock A nonblocking lock method; the ability to limit the duration of a locking attempt.
NSMultiReaderLock The ability for multiple threads to acquire the lock for reading while allowing only a single thread to acquire the lock for writing.
NSRecursiveLock The ability for a single thread to acquire a lock more than once without deadlocking.

These classes use a locking mechanism that causes a thread to sleep while waiting to acquire a lock rather than to poll the system constantly. Thus, lock objects can be used to lock time-consuming operations without causing system performance to degrade. See the class specifications for these classes for further information on their behavior and usage.

Java also has a locking mechanism, which is based on the synchronized keyword. In certain cases, you may want to use the Foundation locking classes instead:


Constants

NSLocking defines the following constants to simplify locking method invocations that take time intervals as parameters.


Constant Type Description
OneSecond long Number of milliseconds in one second
OneMinute long Number of milliseconds in one minute
OneHour long Number of milliseconds in one hour
OneDay long Number of milliseconds in one day
OneWeek long Number of milliseconds in one week
OneYear long Number of milliseconds in one year (defined as 365.2425 days)
OneCentury long Number of milliseconds in one century



Method Types


All methods
lock
unlock


Instance Methods



lock

public void lock()

Attempts to acquire a lock. This method blocks a thread's execution until the lock can be acquired.

An application protects a critical section of code by requiring a thread to acquire a lock before executing the code. Once the critical section is past, the thread relinquishes the lock by invoking unlock.



unlock

public void unlock()

Relinquishes a previously acquired lock.

© 2001 Apple Computer, Inc. (Last Published April 17, 2001)


Table of Contents