Implement kernel semaphores.

Reviewed by:	jhb

2 files changed, 116 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 977ff58..dbbacda 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -54,7 +54,7 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	physio.9 posix4.9 printf.9 psignal.9 \
 	random.9 resettodr.9 resource_int_value.9 resource_query_string.9 \
 	rtalloc.9 rtentry.9 runqueue.9 \
-	sbuf.9 scheduler.9 sleep.9 sleepqueue.9 spl.9 store.9 \
+	sbuf.9 scheduler.9 sema.9 sleep.9 sleepqueue.9 spl.9 store.9 \
 	style.9 suser.9 swi.9 sx.9 sysctl_add_oid.9 sysctl_ctx_init.9 \
 	taskqueue.9 time.9 timeout.9 tvtohz.9 \
 	ucred.9 uidinfo.9 uio.9 \
@@ -155,6 +155,13 @@ MLINKS+=sleep.9 asleep.9 sleep.9 await.9 sleep.9 msleep.9
 MLINKS+=sleepqueue.9 endtsleep.9 sleepqueue.9 sleepinit.9
 MLINKS+=sleepqueue.9 unsleep.9
 MLINKS+=buf.9 bp.9
+MLINKS+=sema.9 sema_init.9
+MLINKS+=sema.9 sema_destroy.9
+MLINKS+=sema.9 sema_post.9
+MLINKS+=sema.9 sema_wait.9
+MLINKS+=sema.9 sema_timedwait.9
+MLINKS+=sema.9 sema_trywait.9
+MLINKS+=sema.9 sema_value.9
 MLINKS+=spl.9 spl0.9
 MLINKS+=spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 spl.9 splimp.9
 MLINKS+=spl.9 splnet.9 spl.9 splsoftclock.9 spl.9 splsofttty.9
diff --git a/share/man/man9/sema.9 b/share/man/man9/sema.9
new file mode 100644
index 0000000..39a91ce
--- /dev/null
+++ b/share/man/man9/sema.9
@@ -0,0 +1,108 @@
+.\"
+.\" 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$
+.\"
+.Dd August 13, 2001
+.Dt SEMA 9
+.Os
+.Sh NAME
+.Nm sema ,
+.Nm sema_init ,
+.Nm sema_destroy ,
+.Nm sema_post ,
+.Nm sema_wait ,
+.Nm sema_timedwait ,
+.Nm sema_trywait ,
+.Nm sema_value
+.Nd kernel counting semaphore
+.Sh SYNOPSIS
+.Fd #include <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 DESCRIPTION
+Counting semaphores provide a mechanism for synchronizing access to a pool of
+resources.
+Unlike mutexes, semaphores do not have the concept of an owner, so they can also
+be useful in situations where one thread needs to acquire a resource, and
+another thread needs to release it.
+Each semaphore has an integer value associated with it.
+Posting (incrementing) always succeeds, but waiting (decrementing) can only
+successfully complete if the resulting value of the semaphore is greater than or
+equal to zero.
+.Pp
+Semaphores should not be used where mutexes and condition variables
+will suffice.
+Semaphores are a more complex synchronization mechanism than mutexes and
+condition variables and are not as efficient.
+.Pp
+Semaphores are created with
+.Fn sema_init ,
+where
+.Fa sema
+is a pointer to space for a
+.Vt struct sema ,
+.Fa value
+is the initial value of the semaphore, and
+.Fa description
+is a pointer toa null-terminated character string that describes the semaphore.
+Semaphores are destroyed with
+.Fn sema_destroy .
+A semaphore is posted (incremented) with
+.Fn sema_post .
+A semaphore is waited on (decremented) with
+.Fn sema_wait ,
+.Fn sema_timedwait ,
+or
+.Fn sema_trywait .
+The
+.Fa timo
+argument to
+.Fn sema_timedwait
+specifies the minimum time in ticks to wait before returning with failure.
+.Fn sema_value
+returns the current value of the semaphore.
+.Pp
+.Fn sema_timedwait
+and
+.Fn sema_trywait
+will return 0 if waiting on the semaphore failed; otherwise a non-zero value
+will be returned to indicate success.
+.Sh SEE ALSO
+.Xr mutex 9
+.Xr condvar 9