.\"
.\" 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 form must reproduce the above copyright
.\"    notice(s), this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
.\" DAMAGE.
.\"
.\" %FreeBSD: src/share/man/man9/condvar.9,v 1.10 2004/06/21 14:11:45 mpp Exp %
.\"
.\" $FreeBSD$
.Dd December 11, 2000
.Dt CONDVAR 9
.Os
.Sh 名称
.Nm condvar ,
.Nm cv_init ,
.Nm cv_destroy ,
.Nm cv_wait ,
.Nm cv_wait_sig ,
.Nm cv_timedwait ,
.Nm cv_timedwait_sig ,
.Nm cv_signal ,
.Nm cv_broadcast ,
.Nm cv_broadcastpri ,
.Nm cv_wmesg
.Nd カーネル状態変数
.Sh 書式
.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" "struct mtx *mp"
.Ft int
.Fn cv_wait_sig "struct cv *cvp" "struct mtx *mp"
.Ft int
.Fn cv_timedwait "struct cv *cvp" "struct mtx *mp" "int timo"
.Ft int
.Fn cv_timedwait_sig "struct cv *cvp" "struct mtx *mp" "int timo"
.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"
.Sh 解説
状態変数は mutex と連携して状態の発生を待つために使用されます。
状態変数は
.Fn cv_init
を使用して作成されます。
ここで
.Fa cvp
は
.Vt struct cv
のための領域へのポインタ、
.Fa desc
はその状態変数を説明するヌルで終端された文字列へのポインタです。
状態変数は
.Fn cv_destroy
を使用して破壊されます。
スレッドは
.Fn cv_wait ,
.Fn cv_wait_sig ,
.Fn cv_timedwait
または
.Fn cv_timedwait_sig
の呼び出しによって、状態変数上でウェイトします。
スレッドは、
1 つのウェイトのブロックを解除するためには
.Fn cv_signal
の、または全てのウェイトのブロックを解除するには
.Fn cv_broadcast
または
.Fn cv_broadcastpri
の呼び出しによってウェイトのブロック解除を行います。
ウェイタを起こすのに加えて、
.Fn cv_broadcastpri
は、高い優先度を持っていない全てのスレッドの優先度を上げることによって、
全てのウェイタが最低でも
.Fa pri
の優先度を持つことを保証します。
.Fn cv_wmesg
は
.Fn cv_init
への最初の呼び出しによって設定された
.Fa cvp
の説明文字列を返します。
.Pp
スレッドは
.Fn cv_wait ,
.Fn cv_wait_sig ,
.Fn cv_timedwait
または
.Fn cv_timedwait_sig
の呼び出しの前に
.Fa mp
を保持しなければなしません。
スレッドがある状態でウェイトするときに、
.Fa mp
はそのスレッドがブロックされる前に不可分に開放され、それから
その関数呼び出しが戻る前に不可分に再獲得されます。
全てのウェイトするものは
.Fa cvp
と連携している同一の
.Fa mp
を渡さなければなりません。
スレッドは
.Fn cv_signal ,
.Fn cv_broadcast
または
.Fn cv_broadcastpri
を呼び出している間は、たとえ引数として渡していないとしても、
.Fa mp
を保持しなければなりません。
.Pp
.Fn cv_wait ,
.Fn cv_wait_sig ,
.Fn cv_timedwait
および
.Fn cv_timedwait_sig
のブロックが解除された時に、これらの呼び出しスレッドが実行可能にされます。
.Fn cv_timedwait
および
.Fn cv_timedwait_sig
はブロックが解除され
.Er EWOULDBLOCK
を返す前に最長
.Fa timo
/
.Dv HZ
秒間ウェイトします。
そうでなければ、0 を返します。
.Fn cv_wait_sig
および
.Fn cv_timedwait_sig
は、シグナルがとらえられた場合には未完のまま
.Er EINTR
または
.Er ERESTART
の値で戻ります。
または、
.Fn cv_signal
または
.Fn cv_broadcast
で通知を受けた場合には 0 の値で戻ります。
.Sh 戻り値
成功の場合には、
.Fn cv_wait_sig ,
.Fn cv_timedwait
および
.Fn cv_timedwait_sig
は 0 を返します。
そうでない場合には、0 ではないエラーコードが返されます。
.Pp
.Fn cv_wmesg
は
.Fn cv_init
に渡された説明文字列を返します。
.Sh エラー
.Fn cv_wait_sig
および
.Fn cv_timedwait_sig
は以下の場合に失敗します。
.Bl -tag -width Er
.It Bq Er EINTR
マスクされていないシグナルがつかまりました。
.It Bq Er ERESTART
マスクされているシグナルがつかまりました。
.El
.Pp
.Fn cv_timedwait
および
.Fn cv_timedwait_sig
は以下の場合に失敗します。
.Bl -tag -width Er
.It Bq Er EWOULDBLOCK
タイムアウトが満了しました。
.El
.Sh 関連項目
.Xr msleep 9 ,
.Xr mtx_pool 9 ,
.Xr mutex 9 ,
.Xr sema 9 ,
.Xr sx 9