Using IRIX Semaphores

• The P operation (mnemonic deplete) decrements the count. If the result is not negative, the operation succeeds and returns. If the result is negative, the operation suspends the calling process until the count has been made nonnegative by another process doing a V operation.

• The V operation (mnemonic revive) increments the count. If this changes the value from negative to nonnegative, one process that was waiting in a P operation is unblocked.

Creating Normal Semaphores

usnewsema(3P)	Allocate a semaphore and give it an initial value.
usfreesema(3P)	Release a semaphore (does not release any process waiting on the semaphore).
usinitsema(3P)	Reset a semaphore value and its metering information (does not release any process waiting on the semaphore).
usctlsema(3P)	Set and reset semaphore metering information and other attributes.
usdumpsema(3P)	Dump semaphore metering information to a file.

To allocate a new shared-arena semaphore and set its initial value, call usnewsema(). Use usctlsema() to enable recursive use of the semaphore and to enable the collection of metering information. You can use the metering information to find out whether a semaphore is a bottleneck or not.

Tip: When reading the reference pages cited above, notice that usnewsema() returns the address of a usema_t object, and all the other functions take the address of a usema_t. That is, usema_t represents the type of the semaphore itself, and you refer to a semaphore by its address. This is different from locks, which are discussed later in this chapter.

Creating Polled Semaphores

You can use polled semaphores to integrate semaphore handling with other events such as file operations, for which you wait with poll(). You cannot combine the use of normal semaphores with the use of polled devices, since one process cannot wait in a poll() call and in a uspsema() call at the same time. The following functions are supplied for creating and controlling polled semaphores:

usnewpollsema(3P)	Create a polled semaphore and give it an initial value.
usopenpollsema(3P)	Assign a file descriptor to a polled semaphore. The file descriptor can be passed to poll() or select(). This must be done before the semaphore can be used.
usclosepollsema(3P)	Release a file descriptor assigned with usopenpollsema().
usfreepollsema(3P)	Release the space occupied by a polled semaphore and invalidate any file descriptors assigned to it.

Using Semaphores

uspsema(3P)	Perform the P operation on either type of semaphore.
usvsema(3P)	Perform the V operation on either type of semaphore.
ustestsema(3P)	Return the current (instantaneous) value of a semaphore.
uscpsema(3P)	Perform the P operation only if the resulting count will be nonnegative.
usinitsema(3P)	Reset a semaphore value and its metering information (does not release any process waiting on the semaphore).
usctlsema(3P)	Set and reset semaphore metering information and other attributes.
usdumpsema(3P)	Dump semaphore metering information to a file.

To perform the P operation on a semaphore of either type, use uspsema(). When the decremented semaphore value is nonnegative the function returns 0. The action when the decremented count would be negative differs between the polled and normal semaphores (see the uspsema(3P) reference page):

• When a normal semaphore count remains or becomes negative, the calling process is blocked; the function does not return until the count is nonnegative.

• When a polled semaphore count remains or becomes negative, the function returns 0 and the calling process must use poll() to find out when it becomes nonnegative.

The uscpsema() function provides a conditional P operation: it performs a P operation on the semaphore only if it can do so without making the value negative. The ustestsema() function returns the current value of the semaphore--which of course is immediately out of date.

The usinitsema() function reinitializes the semaphore to a specified value. Note that if you reinitialize a semaphore on which processes are waiting, the processes continues to wait. You should reinitialize a semaphore only in unusual circumstances.

You can call usctlsema() to enable the keeping of either metering information--cumulative counts of usage--or a history trace. The metering information shows whether a semaphore is a bottleneck in the program's operations. The history trace can be used to analyze bugs.