condvar (9)

Leading comments

Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice(s), this list of conditions and the following disclaimer as
   the first lines of this file unmodified other than the possible
   addition of one or more copyright notices.
2. Redistributions in binary f...

(The comments found at the beginning of the groff file "man9/condvar.9freebsd".)

NAME

condvar cv_init cv_destroy cv_wait cv_wait_sig cv_wait_unlock cv_timedwait cv_timedwait_sbt cv_timedwait_sig cv_timedwait_sig_sbt cv_signal cv_broadcast cv_broadcastpri cv_wmesg - kernel condition variable

SYNOPSIS

In sys/param.h In sys/proc.h In sys/condvar.h Ft void Fn cv_init struct cv *cvp const char *desc Ft void Fn cv_destroy struct cv *cvp Ft void Fn cv_wait struct cv *cvp lock Ft int Fn cv_wait_sig struct cv *cvp lock Ft void Fn cv_wait_unlock struct cv *cvp lock Ft int Fn cv_timedwait struct cv *cvp lock int timo Ft int Fn cv_timedwait_sbt struct cv *cvp lock sbintime_t sbt sbintime_t pr int flags Ft int Fn cv_timedwait_sig struct cv *cvp lock int timo Ft int Fn cv_timedwait_sig_sbt struct cv *cvp lock sbintime_t sbt sbintime_t pr int flags Ft void Fn cv_signal struct cv *cvp Ft void Fn cv_broadcast struct cv *cvp Ft void Fn cv_broadcastpri struct cv *cvp int pri Ft const char * Fn cv_wmesg struct cv *cvp

DESCRIPTION

Condition variables are used in conjunction with mutexes to wait for conditions to occur. Condition variables are created with Fn cv_init , where Fa cvp is a pointer to space for a Vt struct cv , and Fa desc is a pointer to a null-terminated character string that describes the condition variable. Condition variables are destroyed with Fn cv_destroy . Threads wait on condition variables by calling Fn cv_wait , Fn cv_wait_sig , Fn cv_wait_unlock , Fn cv_timedwait , or Fn cv_timedwait_sig . Threads unblock waiters by calling Fn cv_signal to unblock one waiter, or Fn cv_broadcast or Fn cv_broadcastpri to unblock all waiters. In addition to waking waiters, Fn cv_broadcastpri ensures that all of the waiters have a priority of at least Fa pri by raising the priority of any threads that do not. Fn cv_wmesg returns the description string of Fa cvp , as set by the initial call to Fn cv_init .

The Fa lock argument is a pointer to either a mutex(9), rwlock(9), or sx(9) lock. A mutex(9) argument must be initialized with MTX_DEF and not MTX_SPIN A thread must hold Fa lock before calling Fn cv_wait , Fn cv_wait_sig , Fn cv_wait_unlock , Fn cv_timedwait , or Fn cv_timedwait_sig . When a thread waits on a condition, Fa lock is atomically released before the thread is blocked, then reacquired before the function call returns. In addition, the thread will fully drop the Giant mutex (even if recursed) while the it is suspended and will reacquire the Giant mutex before the function returns. The Fn cv_wait_unlock function does not reacquire the lock before returning. Note that the Giant mutex may be specified as Fa lock . However, Giant may not be used as Fa lock for the Fn cv_wait_unlock function. All waiters must pass the same Fa lock in conjunction with Fa cvp .

When Fn cv_wait , Fn cv_wait_sig , Fn cv_wait_unlock , Fn cv_timedwait , and Fn cv_timedwait_sig unblock, their calling threads are made runnable. Fn cv_timedwait and Fn cv_timedwait_sig wait for at most Fa timo / HZ seconds before being unblocked and returning Er EWOULDBLOCK ; otherwise, they return 0. Fn cv_wait_sig and Fn cv_timedwait_sig return prematurely with a value of Er EINTR or Er ERESTART if a signal is caught, or 0 if signaled via Fn cv_signal or Fn cv_broadcast .

Fn cv_timedwait_sbt and Fn cv_timedwait_sig_sbt functions take Fa sbt argument instead of Fa timo . It allows to specify relative or absolute unblock time with higher resolution in form of Vt sbintime_t . The parameter Fa pr allows to specify wanted absolute event precision. The parameter Fa flags allows to pass additional Fn callout_reset_sbt flags.

RETURN VALUES

If successful, Fn cv_wait_sig , Fn cv_timedwait , and Fn cv_timedwait_sig return 0. Otherwise, a non-zero error code is returned.

Fn cv_wmesg returns the description string that was passed to Fn cv_init .

ERRORS

Fn cv_wait_sig and Fn cv_timedwait_sig will fail if:

Bq Er EINTR

A signal was caught and the system call should be interrupted.

Bq Er ERESTART

A signal was caught and the system call should be restarted.

Fn cv_timedwait and Fn cv_timedwait_sig will fail if:

Bq Er EWOULDBLOCK

Timeout expired.

SEE ALSO

locking(9), mtx_pool9, mutex(9), rwlock(9), sema(9), sleep(9), sx(9), timeout(9)