com.webobjects.foundation
Interface NSLocking

All Known Implementing Classes:

NSLock, NSMultiReaderLock, NSRecursiveLock, EOObjectStore, EOEditingContext, EOCooperatingObjectStore, EODatabaseContext

public interface NSLocking

The NSLocking interface 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, a multithreaded application can be considered 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 invoking lock on it, thus putting the object in the locked state. You relinquish a lock by invoking unlock which puts the object in the unlocked state. (The Foundation classes that adopt this interface define additional ways to acquire and relinquish locks.)

The lock method as declared in this interface 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 interface typically add methods that offer nonblocking alternatives.

These Foundation classes conform to the NSLocking interface:

Class	Adds these features to the basic interface
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.

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:

• The Foundation classes have extra features that are not supported by the synchronized locking mechanism like nonblocking lock methods.
• Foundation locking objects can coordinate the locking of many objects at the same time, unlike the synchronized locking mechanism, which can lock only a single method, class, or instance at a time.
• These locking classes were available in previous versions of WebObjects. You may encounter these classes if older applications are being ported to this version of WebObjects.

Field Summary

static long	OneCentury Number of milliseconds in one century
static long	OneDay Number of milliseconds in one day
static long	OneHour Number of milliseconds in one Hour
static long	OneMinute Number of milliseconds in one Minute
static long	OneSecond Number of milliseconds in one Second
static long	OneWeek Number of milliseconds in one Week
static long	OneYear Number of milliseconds in one Year (defined as 365.2425 days)

Method Summary

void	lock() Attempts to acquire a lock.
void	unlock() Relinquishes a previously acquired lock.

Field Detail

OneCentury

public static final long OneCentury

Number of milliseconds in one century

OneDay

public static final long OneDay

Number of milliseconds in one day

OneHour

public static final long OneHour

Number of milliseconds in one Hour

OneMinute

public static final long OneMinute

Number of milliseconds in one Minute

OneSecond

public static final long OneSecond

Number of milliseconds in one Second

OneWeek

public static final long OneWeek

Number of milliseconds in one Week

OneYear

public static final long OneYear

Number of milliseconds in one Year (defined as 365.2425 days)

Method Detail

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.