cde/lib/DtSvc/DtUtil2/Lock.h

   1 /*
   2  * File:         Lock.h $XConsortium: Lock.h /main/4 1995/10/26 15:24:02 rswiston $
   3  * Language:     C
   4  *
   5  * (c) Copyright 1990, Hewlett-Packard Company, all rights reserved.
   6  *
   7  * (c) Copyright 1993, 1994 Hewlett-Packard Company                     *
   8  * (c) Copyright 1993, 1994 International Business Machines Corp.       *
   9  * (c) Copyright 1993, 1994 Sun Microsystems, Inc.                      *
  10  * (c) Copyright 1993, 1994 Novell, Inc.                                *
  11  */
  12
  13 #ifndef _Dt_lock_h
  14 #define _Dt_lock_h
  15
  16 /*
  17     GENERAL DESCRIPTION:
  18
  19         The DT lock facility provides simple exclusive locking.  It
  20         (as of 6/19/90) is based on the X11 selection-ownership
  21         mechanism, though users of Dt locking do not need to be aware of
  22         this.
  23
  24         X11 server grabs are judiciously used to guarantee atomicity of
  25         operations.  If a process which holds a lock dies (or closes its
  26         X11 server connection for some other reason), the lock will be
  27         automatically released.
  28
  29         Locks are identified by a string.  There is no mechanism to
  30         allocate unique lock strings to clients; users must take care to
  31         choose a string that will not be easily duplicated by some other
  32         client.
  33
  34     SAMPLE CODE:
  35
  36         #define MY_LOCK "MYAPP_MY_LOCK"
  37
  38         ...
  39
  40         if (_DtGetLock (display, MY_LOCK)) {
  41            <do whatever it is I want to do>
  42            _DtReleaseLock (display, MY_LOCK);
  43         }
  44         else {
  45            <do the alternative>
  46         }
  47 */
  48
  49 extern int _DtGetLock (
  50    Display *display,
  51    char  *lock_name);
  52 /*
  53     DESCRIPTION:
  54
  55         _DtGetLock attempts to get the specified lock.  If nobody holds
  56         the lock, _DtGetLock will obtain the lock and return 1.  If
  57         somebody else already holds the lock, the lock will not be
  58         disturbed and _DtGetLock will return 0.
  59
  60         If the process which owns a lock dies (or closes its X11 server
  61         connection), the lock will be automatically released.  To
  62         explicitly release a lock, use _DtReleaseLock.
  63
  64
  65     SYNOPSIS:
  66
  67         success = _DtGetLock (display, lock);
  68
  69         int success;            Returns 1 if the lock is obtained,
  70                                 0 if not.
  71
  72         Display *display;       The X11 server connection which will
  73                                 hold the lock.
  74
  75         char *lock;             The string which names the lock.
  76 */
  77
  78 extern void _DtReleaseLock (
  79    Display *display,
  80    char *lock_name);
  81 /*
  82     DESCRIPTION:
  83
  84         _DtReleaseLock releases a lock obtained by _DtGetLock.
  85
  86         WARNING!!  It is perfectly legal for one process to release
  87         a lock held by another process.  By convention you should only
  88         release locks previously obtained by your process from _DtGetLock
  89         unless you are playing God and know what you are doing.
  90
  91     SYNOPSIS:
  92
  93         (void) _DtReleaseLock (display, lock);
  94
  95         Display *display;       The X11 server connection which holds
  96                                 the lock.
  97
  98         char *lock;             The string which names the lock.
  99 */
 100
 101 extern int _DtTestLock (
 102    Display *display,
 103    char *lock_name);
 104 /*
 105     DESCRIPTION:
 106
 107         _DtTestLock returns a status indicating whether anybody holds the
 108         specified lock.
 109
 110     SYNOPSIS:
 111
 112         status = _DtTestLock (display, lock);
 113
 114         int success;            Returns 1 if anybody holds the lock,
 115                                 0 otherwise.
 116
 117         Display *display;       The X11 server connection.
 118
 119         char *lock;             The string which names the lock.
 120 */
 121
 122 #endif /* _Dt_lock_h */
 123 /* Do not add anything after this endif. */