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