diff options
Diffstat (limited to 'share/man/man9')
| -rw-r--r-- | share/man/man9/Makefile | 9 | ||||
| -rw-r--r-- | share/man/man9/sema.9 | 108 |
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 |
