|CONDVAR(9F)||Kernel Functions for Drivers||CONDVAR(9F)|
#include <sys/ksynch.h> void cv_init(kcondvar_t *cvp, char *name, kcv_type_t type, void *arg);
void cv_destroy(kcondvar_t *cvp);
void cv_wait(kcondvar_t *cvp, kmutex_t *mp);
void cv_signal(kcondvar_t *cvp);
void cv_broadcast(kcondvar_t *cvp);
int cv_wait_sig(kcondvar_t *cvp, kmutex_t *mp);
clock_t cv_timedwait(kcondvar_t *cvp, kmutex_t *mp, clock_t timeout);
clock_t cv_timedwait_sig(kcondvar_t *cvp, kmutex_t *mp, clock_t timeout);
clock_t cv_reltimedwait(kcondvar_t *cvp, kmutex_t *mp, clock_t delta, time_res_t res);
clock_t cv_reltimedwait_sig(kcondvar_t *cvp, kmutex_t *mp, clock_t delta, time_res_t res);
Note that the granularity of these functions is in clock ticks, therefore the only values which will have an effect are: TR_SEC and TR_CLOCK_TICK .
The usual use of condition variables is to check a condition (for example, device state, data structure reference count, etc.) while holding a mutex which keeps other threads from changing the condition. If the condition is such that the thread should block, cv_wait() is called with a related condition variable and the mutex. At some later point in time, another thread would acquire the mutex, set the condition such that the previous thread can be unblocked, unblock the previous thread with cv_signal() or cv_broadcast(), and then release the mutex.
cv_wait() suspends the calling thread and exits the mutex atomically so that another thread which holds the mutex cannot signal on the condition variable until the blocking thread is blocked. Before returning, the mutex is reacquired.
cv_signal() signals the condition and wakes one blocked thread. All blocked threads can be unblocked by calling cv_broadcast(). cv_signal() and cv_broadcast() can be called by a thread even if it does not hold the mutex passed into cv_wait(), though holding the mutex is necessary to ensure predictable scheduling.
The function cv_wait_sig() is similar to cv_wait() but returns 0 if a signal (for example, by kill(2)) is sent to the thread. In any case, the mutex is reacquired before returning.
The function cv_timedwait() is similar to cv_wait(), except that it returns −1 without the condition being signaled after the timeout time has been reached.
The function cv_timedwait_sig() is similar to cv_timedwait() and cv_wait_sig(), except that it returns −1 without the condition being signaled after the timeout time has been reached, or 0 if a signal (for example, by kill(2)) is sent to the thread.
For both cv_timedwait() and cv_timedwait_sig(), time is in absolute clock ticks since the last system reboot. The current time may be found by calling ddi_get_lbolt(9F).
The functions cv_reltimedwait() and cv_reltimedwait_sig() behave similarly to cv_timedwait() and cv_timedwait_sig() respectively, except instead of taking a time in absolute clock ticks, they take a relative number of clock ticks to wait. In addition, both functions take an additional argument res, which specifies the desired granularity that the system should default to, generally the value TR_CLOCK_TICK .
If cv_wait(), cv_timedwait(), cv_wait_sig(), cv_timedwait_sig(), cv_reltimedwait(), or cv_reltimedwait_sig(), are used from interrupt context, lower-priority interrupts will not be serviced during the wait. This means that if the thread that will eventually perform the wakeup becomes blocked on anything that requires the lower-priority interrupt, the system will hang.
For example, the thread that will perform the wakeup may need to first allocate memory. This memory allocation may require waiting for paging I/O to complete, which may require a lower-priority disk or network interrupt to be serviced. In general, situations like this are hard to predict, so it is advisable to avoid waiting on condition variables or semaphores in an interrupt context.
Here the condition being waited for is a flag value in a driver's unit structure. The condition variable is also in the unit structure, and the flag word is protected by a mutex in the unit structure.
mutex_enter(&un->un_lock); while (un->un_flag & UNIT_BUSY) cv_wait(&un->un_cv, &un->un_lock); un->un_flag |= UNIT_BUSY; mutex_exit(&un->un_lock);
Example 2 Unblocking Threads Blocked by the Code in Example 1
At some later point in time, another thread would execute the following to unblock any threads blocked by the above code.
mutex_enter(&un->un_lock); un->un_flag &= ~UNIT_BUSY; cv_broadcast(&un->un_cv); mutex_exit(&un->un_lock);
If your driver needs to wait on behalf of processes that have real-time constraints, use cv_timedwait() rather than delay(9F). The delay() function calls timeout(9F), which can be subject to priority inversions.
Not all threads can receive signals from user level processes. In cases where such reception is impossible (such as during execution of close(9E) due to exit(2)), cv_wait_sig() behaves as cv_wait(), cv_timedwait_sig() behaves as cv_timedwait(), and cv_reltimedwait_sig() behaves as cv_reltimedwait(). To avoid unkillable processes, users of these functions may need to protect against waiting indefinitely for events that might not occur. The ddi_can_receive_sig(9F) function is provided to detect when signal reception is possible.
Writing Device Drivers
|March 29, 2016||OmniOS|