.\"
.\" Copyright (C) 2001 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/sema.9,v 1.9 2004/07/07 19:57:15 ru Exp %
.\" $FreeBSD$
.\"
.Dd June 14, 2004
.Dt SEMA 9
.Os
.Sh 名称
.Nm sema ,
.Nm sema_init ,
.Nm sema_destroy ,
.Nm sema_post ,
.Nm sema_wait ,
.Nm sema_timedwait ,
.Nm sema_trywait ,
.Nm sema_value
.Nd カーネル計数セマフォ
.Sh 書式
.In sys/types.h
.In sys/lock.h
.In sys/sema.h
.Ft void
.Fn sema_init "struct sema *sema" "int value" "const char *description"
.Ft void
.Fn sema_destroy "struct sema *sema"
.Ft void
.Fn sema_post "struct sema *sema"
.Ft void
.Fn sema_wait "struct sema *sema"
.Ft int
.Fn sema_timedwait "struct sema *sema" "int timo"
.Ft int
.Fn sema_trywait "struct sema *sema"
.Ft int
.Fn sema_value "struct sema *sema"
.Sh 解説
計数セマフォはリソースのプールへのアクセスの同期のための
仕組みを提供します。
mutex とは違い、セマフォは所有者の概念は持っていないため、
1 つのスレッドがリソースの獲得を必要とし、別のスレッドがそのリソースの
開放を必要とするような状況でも、利用できます。
各々のセマフォは、それに関連付けられた整数値を持っています。
ポスト (インクリメント) は常に成功しますが、ウェイト (デクリメント) は
そのセマフォの値が 0 以上になる場合にのみ、成功して完了することが可能です。
.Pp
セマフォは mutex と状態変数で十分であるようなところでは使用するべきでは
ありません。
セマフォは mutex と状態変数より複雑な同期の仕組みですので、
そのため効率的ではありません。
.Pp
セマフォは
.Fn sema_init
を使用して作成されます。
ここで
.Fa sema
は
.Vt "struct sema"
のための領域へのポインタで、
.Fa value
はセマフォの初期値で、
.Fa description
はそのセマフォを説明するヌルで終端された文字列へのポインタです。
セマフォは
.Fn sema_destroy
を使用して破壊されます。
セマフォは
.Fn sema_post
を使用してポスト (インクリメント) されます。
セマフォは
.Fn sema_wait ,
.Fn sema_timedwait
または
.Fn sema_trywait
を使用してウェイト (デクリメント) されます。
.Fn sema_timedwait
への
.Fa timo
引数は失敗して戻る前にウェイトするための tick 単位での最小時間を指定します。
.Fn sema_value
はセマフォの現在の値を読み出すために使用されます。
.Sh 戻り値
.Fn sema_value
関数は現在のセマフォの値を返します。
.Pp
セマフォのデクリメントによりその値が負になった場合には、
.Fn sema_trywait
は失敗を示すために 0 を返します。
そうでない場合には、成功を示すために 0 ではない値が返されます。
.Pp
.Fn sema_timedwait
関数はそのセマフォ上でのウェイトが成功した場合には 0 を返し、
そうでない場合には 0 ではないエラーコードが返されます。
.Sh エラー
.Fn sema_timedwait
関数は以下の場合に失敗します。
.Bl -tag -width Er
.It Bq Er EWOULDBLOCK
タイムアウトしました。
.El
.Sh 関連項目
.Xr condvar 9 ,
.Xr mtx_pool 9 ,
.Xr mutex 9 ,
.Xr sx 9