A condition variable is a way for a thread to block until some event occurs. A thread can wait on a condition variable, to be woken up when some other thread notifies the condition.
A condition variable is associated with a mutex and, conceptually, with some condition. For proper operation, the mutex must be acquired, and then a waiting thread must loop, testing the condition and waiting on the condition variable. For example:
(with-mutex mutex
(while (not global-variable)
(condition-wait cond-var)))
The mutex ensures atomicity, and the loop is for robustness—there may be spurious notifications.
Similarly, the mutex must be held before notifying the condition. The typical, and best, approach is to acquire the mutex, make the changes associated with this condition, and then notify it:
(with-mutex mutex
(setq global-variable (some-computation))
(condition-notify cond-var))
Make a new condition variable associated with mutex. If name is specified, it is a name given to the condition variable. It must be a string. The name is for debugging purposes only; it has no meaning to Emacs.
This function returns
tif object represents a condition variable,nilotherwise.
Wait for another thread to notify cond, a condition variable. This function will block until the condition is notified, or until a signal is delivered to this thread using
thread-signal.It is an error to call
condition-waitwithout holding the condition's associated mutex.
condition-waitreleases the associated mutex while waiting. This allows other threads to acquire the mutex in order to notify the condition.
Notify cond. The mutex with cond must be held before calling this. Ordinarily a single waiting thread is woken by
condition-notify; but if all is notnil, then all threads waiting on cond are notified.
condition-notifyreleases the associated mutex while waiting. This allows other threads to acquire the mutex in order to wait on the condition.