USGETINFO(3P)                                                    USGETINFO(3P)


NAME
     usgetinfo, usputinfo, uscasinfo - exchange information though an arena

C SYNOPSIS
     #include <ulocks.h>

     void usputinfo (usptr_t *handle, void *info);

     void *usgetinfo (usptr_t *handle);

     int uscasinfo (usptr_t *handle, void *old, void *new);

DESCRIPTION
     When unrelated processes decide to share an arena, it is often useful to
     be able to initially communicate the location of various data structures
     within the arena.  A single word (doubleword in 64 bit mode)
     communication area is available inside the arena header block, accessible
     via the functions usgetinfo and usputinfo.  Thus, a process that sets up
     the arena can initialize various locks, semaphores, and common data
     structures, and place a single pointer that any process that joins the
     arena can retrieve.  usputinfo places the data item in the header,
     overwriting any existing information there.  usgetinfo will retrieve that
     information.  At arena creation time, the value is initialized to zero.

     If multiple unrelated processes are starting at arbitrary times, then a
     race condition exists between initializing the arena and setting the
     global information.  The uscasinfo function provides a compare and swap
     operation on the data item in the arena header block.  To establish race
     free initialization, each joining member should first check the data item
     using usgetinfo and if 0 should allocate a semaphore (using usnewsema).
     The caller should then use uscasinfo to atomically place the semaphore
     pointer into the communication area.  If uscasinfo returns 0 then someone
     else may have beat the caller and the caller should free the semaphore
     and repeat the algorithm starting with re-checking usgetinfo.  Note that
     even with one process performing this algorithm, the compare and swap
     operation may fail, so the caller must always be prepared to loop.  If 1
     is returned, then the caller has won and can use the semaphore for future
     negotiation.

SEE ALSO
     usinit(3P).


                                                                        Page 1