suds_lock(S)

suds_lock -- obtain a spin lock

Syntax

cc . . . -lsuds

#include <sys/semaphore.h>

int suds_lock(struct suds_lock *lock_addr);

Description

The suds_lock( ) function is used to obtain a lock. When a lock has been obtained by a process, any other process or thread that attempts to obtain that lock with suds_lock will wait until the lock is released by the owner of the lock calling the suds_unlock(S) function. This behavior guarantees that any section of code where a particular lock is obtained will only be executed by one process at a time. The amount of time a lock is held for should be as short as possible, since some system activity is postponed until after the lock is released. When the lock is held, no system calls should be used. Systems should be configured to minimize the possibility of page faults occurring while the lock is held. The number of page faults can be minimized by ensuring the system is not paging or swapping.

When multiple locks are locked simultaneously they should always be obtained using canonical ordering. For example, if one function obtains two locks, A and B, in AB order, then there should be no function that obtains them in BA order. No deadlock detection mechanisms are incorporated in the suds_lock and suds_unlock functions.

Return values

Upon successful completion, the function returns 0. Otherwise -1 is returned and errno set accordingly.

Diagnostics

[EINVAL]: The specified address of the lock is not a valid lock address.

Examples

The following code shows an application using a lock to ensure that a variable is atomically updated on the basis of a condition that can be modified by other processes:

   struct suds_lock lock_all;
   .
   .
   .
   suds_lockinit(&lock_all);
   .
   .
   .
   suds_lock(&lock_all);
   if (global_condition)
   	counter = counter + updatevalue;	
   suds_unlock(&lock_all);

Standards conformance

suds_lock is not part of any currently supported standard; it is an extension of AT&T System V provided by The Santa Cruz Operation, Inc.