S_LOCK(3P)

NAME
s_init_lock, s_lock, s_clock, s_unlock - initialize, lock, unlock locks

SYNOPSIS
C syntax:

#include <parallel/parallel.h>
slock_t *lp;
s_init_lock (lp);
S_INIT_LOCK (lp);
s_lock (lp);
S_LOCK (lp);
s_clock (lp);
S_CLOCK (lp);
s_unlock (lp);
S_UNLOCK (lp);

Pascal syntax

procedure s_init_lock(var lp : integer);
cexternal;
procedure s_lock(var lp : integer);
cexternal;
function s_clock : longint;
cexternal;
procedure s_unlock(var lp : integer);
cexternal;

FORTRAN syntax

subroutine s_init_lock(lp)
subroutine s_lock(lp)
subroutine s_clock(lp)
subroutine s_unlock(lp)
integer*1 lp

DESCRIPTION
S_init_lock initializes a memory-based lock. After the lock is initialized, it can be locked with the s_lock or s_clock routine and unlocked with the s_unlock routine. There is no practical limit to the number of locks that can be used by a process.

In the C language, a lock is a shared data structure of type slock_t, as shown in the following declaration statement:

	shared slock_t lock;

In Pascal, a lock is a global integer variable. In FORTRAN, a lock is an INTEGER*1 variable. A FORTRAN lock must be placed in shared memory either by declaring it in a common block and using the loader -F option or by using the FORTRAN compiler -mp option, which places all variables into shared memory.

s_lock and s_clock lock the lock whose address is lp. The lock must previously have been initialized using s_init_lock. s_lock is always successful; it spins as long as is necessary to acquire the lock. s_clock is successful only if the lock is free; if the lock is held by another process, s_clock returns the value L_FAILED. s_clock can be used when a process does not need to acquire a particular lock (for instance, when another lock could be used instead).

s_unlock unlocks the lock whose address is lp.

S_INIT_LOCK, S_LOCK, S_UNLOCK, and S_CLOCK are C-preprocessor macros. (The S_CLOCK macro is actually compiled out of line on Balance systems, but it is available for code compatibility.) These macros are found in the header file /usr/include/parallel/parallel.h. The macros are faster than the normal function calls, but they can add to the code size. See the source code in <parallel/parallel.h> for more information on the macros.

SEE ALSO
intro(3P), shmalloc(3P), fortran(1), ld(1), Guide to Parallel Programming

NOTES
The function names s_init_lock, s_lock, s_clock, and s_unlock are used in C, Pascal, and FORTRAN. In C, the lp argument is passed as a pointer to the lock, while in Pascal and FORTRAN, the argument is the address of the lock itself.

BUGS
s_lock, s_unlock, and s_init_lock are declared as integer functions, but do not in fact return a value.