Subversion Repositories planix.SVN

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 - 1 
.TH SEMACQUIRE 2
2 
.SH NAME
3 
semacquire, tsemacquire, semrelease - user level semaphores
4 
.SH SYNOPSIS
5 
.B #include <u.h>
6 
.br
7 
.B #include <libc.h>
8 
.PP
9 
.B
10 
int semacquire(long *addr, int block);
11 
.PP
12 
.B
13 
int tsemacquire(long *addr, ulong ms);
14 
.PP
15 
.B
16 
long semrelease(long *addr, long count);
17 
.SH DESCRIPTION
18 
.IR Semacquire ,
19 
.IR tsemacquire ,
20 
and
21 
.I semrelease
22 
facilitate scheduling between processes sharing memory.
23 
Processes arrange to share memory by using
24 
.I rfork
25 
with the
26 
.B RFMEM
27 
flag
28 
(see
29 
.IR fork (2)),
30 
.IR segattach (2),
31 
or
32 
.IR thread (2).
33 
.PP
34 
The semaphore's value is the integer pointed at by
35 
.IR addr .
36 
.I Semacquire
37 
atomically waits until the semaphore has a positive value
38 
and then decrements that value.
39 
If
40 
.I block
41 
is zero
42 
and the semaphore is not immediately available,
43 
.I semacquire
44 
returns 0 instead of waiting.
45 
.I Tsemacquire
46 
only waits
47 
.I ms
48 
milliseconds for the semaphore to attain a positive value
49 
and, if available in that time, decrements that value.
50 
It returns 0 otherwise.
51 
Both functions return 1 if the semaphore was acquired
52 
and -1 on error
53 
(e.g., if they were interrupted).
54 
.I Semrelease
55 
adds
56 
.I count
57 
to the semaphore's value
58 
and returns the new value.
59 
.PP
60 
.I Semacquire
61 
(and analogously for
62 
.IR tsemacquire )
63 
and
64 
.I semrelease
65 
can be thought of as efficient, correct replacements for:
66 
.IP
67 
.EX
68 
int
69 
semacquire(long *addr, int block)
70 
{
71 
	while(*addr == 0){
72 
		if(!block)
73 
			return 0;
74 
		if(interrupted)
75 
			return -1;
76 
	}
77 
	--*addr;
78 
	return 1;
79 
}
80 
 
81 
int
82 
semrelease(long *addr, int count)
83 
{
84 
	return *addr += count;
85 
}
86 
.EE
87 
.PP
88 
Like
89 
.IR rendezvous (2),
90 
.IR semacquire ,
91 
.IR tsemacquire ,
92 
and
93 
.I semrelease
94 
are not typically used directly.
95 
Instead, they are intended to be used to coordinate
96 
scheduling in higher-level abstractions such as
97 
locks, rendezvous points, and channels
98 
(see
99 
.IR lock (2)
100 
and
101 
.IR thread (2)).
102 
Also like
103 
.IR rendezvous ,
104 
.IR semacquire ,
105 
.IR tsemacquire ,
106 
and
107 
.I semrelease
108 
cannot be used to coordinate between threads
109 
in a single process.
110 
Use locks, rendezvous points, or channels instead.
111 
.SH SOURCE
112 
.B /sys/src/9/port/sysproc.c
113 
.SH SEE ALSO
114 
.IR fork (2),
115 
.IR lock (2),
116 
.IR rendezvous (2),
117 
.IR segattach (2),
118 
.IR thread (2)
119 
.SH DIAGNOSTICS
120 
These functions set
121 
.IR errstr .