---

NSConditionLock Class Reference

Overview

The NSConditionLock class defines objects whose locks can be associated with specific, user-defined conditions. Using an NSConditionLock object, you can ensure that a thread can acquire a lock only if a certain condition is met. Once it has acquired the lock and executed the critical section of code, the thread can relinquish the lock and set the associated condition to something new. The conditions themselves are arbitrary: you define them as needed for your application.

Adopted Protocols

• lock

• unlock

Tasks

Initializing an NSConditionLock Object

• – initWithCondition:

Returning the Condition

• – condition

Acquiring and Releasing a Lock

• – lockBeforeDate:
• – lockWhenCondition:
• – lockWhenCondition:beforeDate:
• – tryLock
• – tryLockWhenCondition:
• – unlockWithCondition:

Accessor Methods

• – setName:
• – name

Instance Methods

condition

Returns the condition associated with the receiver.

- (NSInteger)condition

Return Value

The condition associated with the receiver. If no condition has been set, returns 0.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSLock.h

initWithCondition:

Initializes a newly allocated NSConditionLock object and sets its condition.

- (id)initWithCondition:(NSInteger)condition

Parameters

condition

The user-defined condition for the lock. The value of condition is user-defined; see the class description for more information.

Return Value

An initialized condition lock object; may be different than the original receiver.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• QTAudioExtractionPanel
• Vertex Optimization

Declared In

NSLock.h

lockBeforeDate:

Attempts to acquire a lock before a specified moment in time.

- (BOOL)lockBeforeDate:(NSDate *)limit

Parameters

limit

The date by which the lock must be acquired or the attempt will time out.

Return Value

YES if the lock is acquired within the time limit, NO otherwise.

Discussion

The condition associated with the receiver isn’t taken into account in this operation. This method blocks the thread’s execution until the receiver acquires the lock or limit is reached.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lockWhenCondition:beforeDate:

Declared In

NSLock.h

lockWhenCondition:

Attempts to acquire a lock.

- (void)lockWhenCondition:(NSInteger)condition

Parameters

condition

The condition to match on.

Discussion

The receiver’s condition must be equal to condition before the locking operation will succeed. This method blocks the thread’s execution until the lock can be acquired.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lockWhenCondition:beforeDate:
• – unlockWithCondition:

Declared In

NSLock.h

lockWhenCondition:beforeDate:

Attempts to acquire a lock before a specified moment in time.

- (BOOL)lockWhenCondition:(NSInteger)condition beforeDate:(NSDate *)limit

Parameters

condition

The condition to match on.

limit

The date by which the lock must be acquired or the attempt will time out.

Return Value

YES if the lock is acquired within the time limit, NO otherwise.

Discussion

The receiver’s condition must be equal to condition before the locking operation will succeed. This method blocks the thread’s execution until the lock can be acquired or limit is reached.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lockBeforeDate:
• – lockWhenCondition:

Declared In

NSLock.h

name

Returns the name associated with the receiver.

- (NSString *)name

Return Value

The name of the receiver.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setName:

Declared In

NSLock.h

setName:

Assigns a name to the receiver.

- (void)setName:(NSString *)newName

Parameters

newName

The new name for the receiver. This method makes a copy of the specified string.

Discussion

You can use a name string to identify a condition lock within your code. Cocoa also uses this name as part of any error descriptions involving the receiver.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – name

Declared In

NSLock.h

tryLock

Attempts to acquire a lock without regard to the receiver’s condition.

- (BOOL)tryLock

Return Value

YES if the lock could be acquired, NO otherwise.

Discussion

This method returns immediately.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – tryLockWhenCondition:

Declared In

NSLock.h

tryLockWhenCondition:

Attempts to acquire a lock if the receiver’s condition is equal to the specified condition.

- (BOOL)tryLockWhenCondition:(NSInteger)condition

Return Value

YES if the lock could be acquired, NO otherwise.

Discussion

As part of its implementation, this method invokes lockWhenCondition:beforeDate:. This method returns immediately.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – tryLock

Declared In

NSLock.h

unlockWithCondition:

Relinquishes the lock and sets the receiver’s condition.

- (void)unlockWithCondition:(NSInteger)condition

Parameters

condition

The user-defined condition for the lock. The value of condition is user-defined; see the class description for more information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – lockWhenCondition:

Declared In

NSLock.h

---