latch_wait(S-osr5)

latch_wait, latch_trywait -- acquire a latch

Syntax

cc . . . -lsuds

#include <latch.h>

int latch_wait(latch_t *latch, int type, int timeout);

int latch_trywait(latch_t *latch, int type, int timeout);

Description

latch_wait- acquire a latch; block if latch is already held

latch_trywait- acquire a latch; return an error if latch is already held

The latch_wait function locks the latch referenced by latch by performing the latch lock operation on that latch. If the latch is currently locked by another process, then the calling process does not return from the call to latch_wait until it locks the latch, the call is interrupted by a signal or the timeout expires. The mechanism by which the process blocks is controlled by the latch type as set by the process which is currently holding the latch. The timeout is also set by the process holding the latch.

The latch_trywait function locks the latch referenced by latch only if the latch is currently not locked. Otherwise it does not lock the latch.

Upon successful return, the state of the latch is locked and owned by the calling process. It remains locked until the latch_post(S-osr5) function is executed and returns successfully.

A latch's blocking mechanism is not fixed. It is modified by calls to latch_wait and latch_trywait. There are several available blocking mechanisms:

LT_SPIN: Blocked processes spin waiting for the latch. This is efficient only if the process holding the latch does so for a period of time less than about 17000 CPU cycles. If the latch is likely to be held for longer than this period, or system calls will be made by the process whilst holding the latch, it is strongly recommended that LT_SLEEP be used.
LT_SLEEP: Blocked processes sleep (see sleep(D3oddi)). This is efficient if the latch is likely to be held for a period of time greater than about 17000 CPU cycles or if system calls will be made whilst holding the latch.
LT_SPIN_SLEEP: The process spins until the timeout occurs. When the timeout occurs the process blocks using sleep(D3oddi) with an indefinite timeout.

timeout controls the amount of time latch_wait blocks for before returning with an error condition modifying how it blocks. timeout is in microseconds and has a maximum value of 268435455; a value of 0 represents an indefinite wait. For LT_SPIN and LT_SPIN_SLEEP locks, all processes blocking on a particular latch increment a global value representing the total spin time on that latch since it was last acquired. The timeout occurs when the global value reaches timeout.

Return values

The latch_wait and latch_trywait functions return zero if the calling process successfully performed the latch lock operation on the latch designated by latch. If the call was unsuccessful, the state of the latch remains unchanged and the function returns -1 and sets errno to indicate the error.

Diagnostics

Errors returned are as for sem_wait(S-osr5) together with the following additional error:

[ETIME]: A timeout interrupted this function.

Warning

If a process exits or execs whilst holding a latch the system will post the latch and produce the following warning message on the system console:

   WARNING: latches held at exec/close time

Standards conformance

latch_wait and latch_trywait are not part of any currently supported standard; they are an extension of AT&T System V provided by The Santa Cruz Operation, Inc.