lock-and-condition-variable-wait

lock-and-condition-variable-wait Function

Summary

Locks a lock and calls a predicate. If this returns nil, performs the equivalent of condition-variable-wait. Optionally calls a function on return.

Package

Signature

lock-and-condition-variable-wait lock condvar predicate &key args return-function return-function-args lock-timeout lock-wait-reason condvar-timeout condvar-wait-reason => result

Arguments

`lock`⇩	A lock.
`condvar`⇩	A condition-variable.
`predicate`⇩	A function designator.
`args`⇩	Arguments to`predicate`.
`return-function`⇩	A function designator or `nil`.
`return-function-args`⇩	Arguments to `return-function`.
`lock-timeout`⇩	A non-negative real or `nil`.
`lock-wait-reason`⇩	A string or `nil`.
`condvar-timeout`⇩	A non-negative real or `nil`.
`condvar-wait-reason`⇩	A string or `nil`.

Values

result

See below.

Description

The function lock-and-condition-variable-wait first locks the lock lock as in with-lock, using lock-wait-reason and lock-timeout for the whostate and timeout arguments of with-lock.

It then applies predicate to args. If this call returns nil it performs the equivalent of a call to condition-variable-wait, passing it condvar, lock, condvar-timeout and condvar-wait-reason.

If return-function is supplied, it is then applied to return-function-args, and the return value(s) are returned.

Before returning, lock is unlocked (in an unwinding form) as in with-lock.

lock-and-condition-variable-wait returns whatever return-function returns if it is supplied. If return-function is not supplied, lock-and-condition-variable-wait returns the result of predicate if this is not nil, otherwise it returns the result of the equivalent call to condition-variable-wait.

Notes

predicate and return-function are called with lock held, so they should do as little as needed, and avoid locking anything else.
lock-and-condition-variable-wait makes it much easier to avoid mistakes when using condition-variables.
When return-function is not supplied, lock-and-condition-variable-wait does not lock on return, which makes it it much more efficient than the equivalent code using with-lock and condition-variable-wait.
When return-function is not needed, simple-lock-and-condition-variable-wait may be more convenient.
All the four signaling functions (condition-variable-signal, condition-variable-broadcast, lock-and-condition-variable-signal, lock-and-condition-variable-broadcast) can be used to wake a process waiting in lock-and-condition-variable-wait.