xref: /freebsd/share/man/man9/sema.9 (revision f16b3c0de48d0b845357e7cca843f645bc3117e3)
154db32e9SJason Evans.\"
254db32e9SJason Evans.\" Copyright (C) 2001 Jason Evans <jasone@FreeBSD.org>.  All rights reserved.
354db32e9SJason Evans.\"
454db32e9SJason Evans.\" Redistribution and use in source and binary forms, with or without
554db32e9SJason Evans.\" modification, are permitted provided that the following conditions
654db32e9SJason Evans.\" are met:
754db32e9SJason Evans.\" 1. Redistributions of source code must retain the above copyright
854db32e9SJason Evans.\"    notice(s), this list of conditions and the following disclaimer as
954db32e9SJason Evans.\"    the first lines of this file unmodified other than the possible
1054db32e9SJason Evans.\"    addition of one or more copyright notices.
1154db32e9SJason Evans.\" 2. Redistributions in binary form must reproduce the above copyright
1254db32e9SJason Evans.\"    notice(s), this list of conditions and the following disclaimer in the
1354db32e9SJason Evans.\"    documentation and/or other materials provided with the distribution.
1454db32e9SJason Evans.\"
1554db32e9SJason Evans.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
1654db32e9SJason Evans.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1754db32e9SJason Evans.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1854db32e9SJason Evans.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
1954db32e9SJason Evans.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
2054db32e9SJason Evans.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
2154db32e9SJason Evans.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
2254db32e9SJason Evans.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2354db32e9SJason Evans.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
2454db32e9SJason Evans.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
2554db32e9SJason Evans.\" DAMAGE.
2654db32e9SJason Evans.\"
2754db32e9SJason Evans.\" $FreeBSD$
2854db32e9SJason Evans.\"
2954db32e9SJason Evans.Dd August 13, 2001
3054db32e9SJason Evans.Dt SEMA 9
3154db32e9SJason Evans.Os
3254db32e9SJason Evans.Sh NAME
3354db32e9SJason Evans.Nm sema ,
3454db32e9SJason Evans.Nm sema_init ,
3554db32e9SJason Evans.Nm sema_destroy ,
3654db32e9SJason Evans.Nm sema_post ,
3754db32e9SJason Evans.Nm sema_wait ,
3854db32e9SJason Evans.Nm sema_timedwait ,
3954db32e9SJason Evans.Nm sema_trywait ,
4054db32e9SJason Evans.Nm sema_value
4154db32e9SJason Evans.Nd kernel counting semaphore
4254db32e9SJason Evans.Sh SYNOPSIS
43e81abd74SBruce Evans.In sys/types.h
44f16b3c0dSChad David.In sys/lock.h
45867c1e49SRuslan Ermilov.In sys/sema.h
4654db32e9SJason Evans.Ft void
4754db32e9SJason Evans.Fn sema_init "struct sema *sema" "int value" "const char *description"
4854db32e9SJason Evans.Ft void
4954db32e9SJason Evans.Fn sema_destroy "struct sema *sema"
5054db32e9SJason Evans.Ft void
5154db32e9SJason Evans.Fn sema_post "struct sema *sema"
5254db32e9SJason Evans.Ft void
5354db32e9SJason Evans.Fn sema_wait "struct sema *sema"
5454db32e9SJason Evans.Ft int
5554db32e9SJason Evans.Fn sema_timedwait "struct sema *sema" "int timo"
5654db32e9SJason Evans.Ft int
5754db32e9SJason Evans.Fn sema_trywait "struct sema *sema"
5854db32e9SJason Evans.Ft int
5954db32e9SJason Evans.Fn sema_value "struct sema *sema"
6054db32e9SJason Evans.Sh DESCRIPTION
6154db32e9SJason EvansCounting semaphores provide a mechanism for synchronizing access to a pool of
6254db32e9SJason Evansresources.
6354db32e9SJason EvansUnlike mutexes, semaphores do not have the concept of an owner, so they can also
6454db32e9SJason Evansbe useful in situations where one thread needs to acquire a resource, and
6554db32e9SJason Evansanother thread needs to release it.
6654db32e9SJason EvansEach semaphore has an integer value associated with it.
6754db32e9SJason EvansPosting (incrementing) always succeeds, but waiting (decrementing) can only
6854db32e9SJason Evanssuccessfully complete if the resulting value of the semaphore is greater than or
6954db32e9SJason Evansequal to zero.
7054db32e9SJason Evans.Pp
7154db32e9SJason EvansSemaphores should not be used where mutexes and condition variables
7254db32e9SJason Evanswill suffice.
7354db32e9SJason EvansSemaphores are a more complex synchronization mechanism than mutexes and
74867c1e49SRuslan Ermilovcondition variables, and are not as efficient.
7554db32e9SJason Evans.Pp
7654db32e9SJason EvansSemaphores are created with
7754db32e9SJason Evans.Fn sema_init ,
7854db32e9SJason Evanswhere
7954db32e9SJason Evans.Fa sema
8054db32e9SJason Evansis a pointer to space for a
81867c1e49SRuslan Ermilov.Vt "struct sema" ,
8254db32e9SJason Evans.Fa value
8354db32e9SJason Evansis the initial value of the semaphore, and
8454db32e9SJason Evans.Fa description
8554db32e9SJason Evansis a pointer to a null-terminated character string that describes the semaphore.
8654db32e9SJason EvansSemaphores are destroyed with
8754db32e9SJason Evans.Fn sema_destroy .
8854db32e9SJason EvansA semaphore is posted (incremented) with
8954db32e9SJason Evans.Fn sema_post .
9054db32e9SJason EvansA semaphore is waited on (decremented) with
9154db32e9SJason Evans.Fn sema_wait ,
9254db32e9SJason Evans.Fn sema_timedwait ,
9354db32e9SJason Evansor
9454db32e9SJason Evans.Fn sema_trywait .
9554db32e9SJason EvansThe
9654db32e9SJason Evans.Fa timo
9754db32e9SJason Evansargument to
9854db32e9SJason Evans.Fn sema_timedwait
9954db32e9SJason Evansspecifies the minimum time in ticks to wait before returning with failure.
10054db32e9SJason Evans.Fn sema_value
10154db32e9SJason Evansreturns the current value of the semaphore.
10254db32e9SJason Evans.Pp
10354db32e9SJason Evans.Fn sema_timedwait
10454db32e9SJason Evansand
10554db32e9SJason Evans.Fn sema_trywait
10654db32e9SJason Evanswill return 0 if waiting on the semaphore failed; otherwise a non-zero value
10754db32e9SJason Evanswill be returned to indicate success.
10854db32e9SJason Evans.Sh SEE ALSO
109867c1e49SRuslan Ermilov.Xr condvar 9 ,
11042e5dee9SMike Silbersack.Xr mutex 9 ,
11142e5dee9SMike Silbersack.Xr sx 9
112