USNEWPOLLSEMA(3P)USNEWPOLLSEMA(3P)NAMEusnewpollsema - allocate and initialize a pollable semaphore
C SYNOPSIS
#include <ulocks.h>
usema_t *usnewpollsema (usptr_t *handle, int val);
DESCRIPTIONusnewpollsema allocates a semaphore and initializes its count to the
value specified by val. Initially, metering and debugging are off (and
can be turned on through a call to usctlsema(3P)) and the history logging
mechanism is set according to the global setting (see usconfig(3P)). The
semaphore is allocated from the shared arena designated by handle as
returned from usinit(3P). Pollable semaphores never block the caller.
If the semaphore is unavailable when uspsema(3P) is called, the caller is
queued to receive the semaphore and returns immediately. To actually
acquire the semaphore the caller must issue a poll(2) or select(2) on the
file descriptor associated with the semaphore. A file descriptor is
allocated via usopenpollsema(3P). The POLLIN event should be used with
poll(2). The semaphore file descriptor should be passed in as a read
descriptor for select(2).
A val of 0 implies no available resources, and the first process that
attempts a 'P' operation (via uspsema(3P)) will return 0. This can be
viewed as a synchronizing semaphore, since the goal is to always have a
process wait until another has completed an operation that the first
process requires. Positive values for val can be used for tracking a
collection of resources. The simplest case of a value of 1 implements
the common mutual exclusion semaphore, where one and only one process
will be permitted through a semaphore at a time. Values greater than one
imply that up to val resources may be simultaneously used, but requests
for more than val resources cause the calling process to wait until a
resource comes free (by a process holding a resource performing a
usvsema(3P)).
Pollable semaphores may be used with all the other semaphore routines.
They must be freed using usfreepollsema(3P).
usnewpollsema will fail if one or more of the following are true:
[ENOMEM] There is no memory available in the arena to allocate the
semaphore structure (see usconfig(3P)). Pollable
semaphores take more memory than non-pollable semaphores
since a file descriptor per user must be saved.
[EINVAL] val is less than zero or greater than 30000.
SEE ALSOpoll(2), select(2), amalloc(3P), uscpsema(3P), usconfig(3P),
usctlsema(3P), usdumpsema(3P), usclosepollsema(3P), usfreesema(3P),
usfreepollsema(3P), usinit(3P), usnewsema(3P), usopenpollsema(3P),
Page 1
USNEWPOLLSEMA(3P)USNEWPOLLSEMA(3P)usvsema(3P).
DIAGNOSTICS
Upon successful completion, a value of pointer to a usema_t structure is
returned. Otherwise, a value of NULL is returned and errno is set to
indicate the error.
Page 2
