plan9fox/sys/man/2/semacquire

.TH SEMACQUIRE 2
.SH NAME
semacquire, tsemacquire, semrelease - user level semaphores
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int semacquire(long *addr, int block);
.PP
.B
int tsemacquire(long *addr, ulong ms);
.PP
.B
long semrelease(long *addr, long count);
.SH DESCRIPTION
.IR Semacquire ,
.IR tsemacquire ,
and
.I semrelease
facilitate scheduling between processes sharing memory.
Processes arrange to share memory by using
.I rfork
with the
.B RFMEM
flag
(see
.IR fork (2)),
.IR segattach (2),
or
.IR thread (2).
.PP
The semaphore's value is the integer pointed at by
.IR addr .
.I Semacquire
atomically waits until the semaphore has a positive value
and then decrements that value.
If
.I block
is zero
and the semaphore is not immediately available,
.I semacquire
returns 0 instead of waiting.
.I Tsemacquire
only waits
.I ms
milliseconds for the semaphore to attain a positive value
and, if available in that time, decrements that value.
It returns 0 otherwise.
Both functions return 1 if the semaphore was acquired
and -1 on error
(e.g., if they were interrupted).
.I Semrelease
adds
.I count
to the semaphore's value
and returns the new value.
.PP
.I Semacquire
(and analogously for
.IR tsemacquire )
and
.I semrelease
can be thought of as efficient, correct replacements for:
.IP
.EX
int
semacquire(long *addr, int block)
{
	while(*addr == 0){
		if(!block)
			return 0;
		if(interrupted)
			return -1;
	}
	--*addr;
	return 1;
}

int
semrelease(long *addr, int count)
{
	return *addr += count;
}
.EE
.PP
Like
.IR rendezvous (2),
.IR semacquire ,
.IR tsemacquire ,
and
.I semrelease
are not typically used directly.
Instead, they are intended to be used to coordinate
scheduling in higher-level abstractions such as
locks, rendezvous points, and channels
(see
.IR lock (2)
and
.IR thread (2)).
Also like
.IR rendezvous ,
.IR semacquire ,
.IR tsemacquire ,
and
.I semrelease
cannot be used to coordinate between threads
in a single process.
Use locks, rendezvous points, or channels instead.
.SH SOURCE
.B /sys/src/9/port/sysproc.c
.SH SEE ALSO
.IR fork (2),
.IR lock (2),
.IR rendezvous (2),
.IR segattach (2),
.IR thread (2)
.SH DIAGNOSTICS
These functions set
.IR errstr .