sema.9 (a280550abf7f97914cd92e86e0e698b51c48a46c) sema.9 (54db32e945d6413aeddd438d91dfcbd6eea60b4c)
1.\"
2.\" Copyright (C) 2001 Jason Evans <jasone@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice(s), this list of conditions and the following disclaimer as

--- 12 unchanged lines hidden (view full) ---

21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
25.\" DAMAGE.
26.\"
27.\" $FreeBSD$
28.\"
1.\"
2.\" Copyright (C) 2001 Jason Evans <jasone@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice(s), this list of conditions and the following disclaimer as

--- 12 unchanged lines hidden (view full) ---

21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
25.\" DAMAGE.
26.\"
27.\" $FreeBSD$
28.\"
29.Dd February 1, 2006
29.Dd August 13, 2001
30.Dt SEMA 9
31.Os
32.Sh NAME
33.Nm sema ,
34.Nm sema_init ,
35.Nm sema_destroy ,
36.Nm sema_post ,
37.Nm sema_wait ,
38.Nm sema_timedwait ,
39.Nm sema_trywait ,
40.Nm sema_value
41.Nd kernel counting semaphore
42.Sh SYNOPSIS
30.Dt SEMA 9
31.Os
32.Sh NAME
33.Nm sema ,
34.Nm sema_init ,
35.Nm sema_destroy ,
36.Nm sema_post ,
37.Nm sema_wait ,
38.Nm sema_timedwait ,
39.Nm sema_trywait ,
40.Nm sema_value
41.Nd kernel counting semaphore
42.Sh SYNOPSIS
43.In sys/types.h
44.In sys/lock.h
45.In sys/sema.h
43.Fd #include <sys/sema.h>
46.Ft void
47.Fn sema_init "struct sema *sema" "int value" "const char *description"
48.Ft void
49.Fn sema_destroy "struct sema *sema"
50.Ft void
51.Fn sema_post "struct sema *sema"
52.Ft void
53.Fn sema_wait "struct sema *sema"

--- 12 unchanged lines hidden (view full) ---

66Each semaphore has an integer value associated with it.
67Posting (incrementing) always succeeds, but waiting (decrementing) can only
68successfully complete if the resulting value of the semaphore is greater than or
69equal to zero.
70.Pp
71Semaphores should not be used where mutexes and condition variables
72will suffice.
73Semaphores are a more complex synchronization mechanism than mutexes and
44.Ft void
45.Fn sema_init "struct sema *sema" "int value" "const char *description"
46.Ft void
47.Fn sema_destroy "struct sema *sema"
48.Ft void
49.Fn sema_post "struct sema *sema"
50.Ft void
51.Fn sema_wait "struct sema *sema"

--- 12 unchanged lines hidden (view full) ---

64Each semaphore has an integer value associated with it.
65Posting (incrementing) always succeeds, but waiting (decrementing) can only
66successfully complete if the resulting value of the semaphore is greater than or
67equal to zero.
68.Pp
69Semaphores should not be used where mutexes and condition variables
70will suffice.
71Semaphores are a more complex synchronization mechanism than mutexes and
74condition variables, and are not as efficient.
72condition variables and are not as efficient.
75.Pp
76Semaphores are created with
77.Fn sema_init ,
78where
79.Fa sema
80is a pointer to space for a
73.Pp
74Semaphores are created with
75.Fn sema_init ,
76where
77.Fa sema
78is a pointer to space for a
81.Vt "struct sema" ,
79.Vt struct sema ,
82.Fa value
83is the initial value of the semaphore, and
84.Fa description
80.Fa value
81is the initial value of the semaphore, and
82.Fa description
85is a pointer to a null-terminated character string that describes the semaphore.
83is a pointer toa null-terminated character string that describes the semaphore.
86Semaphores are destroyed with
87.Fn sema_destroy .
88A semaphore is posted (incremented) with
89.Fn sema_post .
90A semaphore is waited on (decremented) with
91.Fn sema_wait ,
92.Fn sema_timedwait ,
93or
94.Fn sema_trywait .
95The
96.Fa timo
97argument to
98.Fn sema_timedwait
99specifies the minimum time in ticks to wait before returning with failure.
100.Fn sema_value
84Semaphores are destroyed with
85.Fn sema_destroy .
86A semaphore is posted (incremented) with
87.Fn sema_post .
88A semaphore is waited on (decremented) with
89.Fn sema_wait ,
90.Fn sema_timedwait ,
91or
92.Fn sema_trywait .
93The
94.Fa timo
95argument to
96.Fn sema_timedwait
97specifies the minimum time in ticks to wait before returning with failure.
98.Fn sema_value
101is used to read the current value of the semaphore.
102.Sh RETURN VALUES
103The
104.Fn sema_value
105function
106returns the current value of the semaphore.
107.Pp
99returns the current value of the semaphore.
100.Pp
108If decrementing the semaphore would result in its value being negative,
109.Fn sema_trywait
110returns 0 to indicate failure.
111Otherwise, a non-zero value is returned to indicate success.
112.Pp
113The
114.Fn sema_timedwait
101.Fn sema_timedwait
115function
116returns 0 if waiting on the semaphore succeeded; otherwise a
117non-zero error code is returned.
118.Sh ERRORS
119The
120.Fn sema_timedwait
121function will fail if:
122.Bl -tag -width Er
123.It Bq Er EWOULDBLOCK
124Timeout expired.
125.El
102and
103.Fn sema_trywait
104will return 0 if waiting on the semaphore failed; otherwise a non-zero value
105will be returned to indicate success.
126.Sh SEE ALSO
106.Sh SEE ALSO
127.Xr condvar 9 ,
128.Xr locking 9 ,
129.Xr mtx_pool 9 ,
130.Xr mutex 9 ,
131.Xr rwlock 9 ,
132.Xr sx 9
107.Xr mutex 9
108.Xr condvar 9