cde/lib/DtSvc/DtUtil2/Lock.h

   1 /*
   2  * CDE - Common Desktop Environment
   3  *
   4  * Copyright (c) 1993-2012, The Open Group. All rights reserved.
   5  *
   6  * These libraries and programs are free software; you can
   7  * redistribute them and/or modify them under the terms of the GNU
   8  * Lesser General Public License as published by the Free Software
   9  * Foundation; either version 2 of the License, or (at your option)
  10  * any later version.
  11  *
  12  * These libraries and programs are distributed in the hope that
  13  * they will be useful, but WITHOUT ANY WARRANTY; without even the
  14  * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE. See the GNU Lesser General Public License for more
  16  * details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with these libraries and programs; if not, write
  20  * to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
  21  * Floor, Boston, MA 02110-1301 USA
  22  */
  23 /*
  24  * File:         Lock.h $XConsortium: Lock.h /main/4 1995/10/26 15:24:02 rswiston $
  25  * Language:     C
  26  *
  27  * (c) Copyright 1990, Hewlett-Packard Company, all rights reserved.
  28  *
  29  * (c) Copyright 1993, 1994 Hewlett-Packard Company                     *
  30  * (c) Copyright 1993, 1994 International Business Machines Corp.       *
  31  * (c) Copyright 1993, 1994 Sun Microsystems, Inc.                      *
  32  * (c) Copyright 1993, 1994 Novell, Inc.                                *
  33  */
  34
  35 #ifndef _Dt_lock_h
  36 #define _Dt_lock_h
  37
  38 /*
  39     GENERAL DESCRIPTION:
  40
  41         The DT lock facility provides simple exclusive locking.  It
  42         (as of 6/19/90) is based on the X11 selection-ownership
  43         mechanism, though users of Dt locking do not need to be aware of
  44         this.
  45
  46         X11 server grabs are judiciously used to guarantee atomicity of
  47         operations.  If a process which holds a lock dies (or closes its
  48         X11 server connection for some other reason), the lock will be
  49         automatically released.
  50
  51         Locks are identified by a string.  There is no mechanism to
  52         allocate unique lock strings to clients; users must take care to
  53         choose a string that will not be easily duplicated by some other
  54         client.
  55
  56     SAMPLE CODE:
  57
  58         #define MY_LOCK "MYAPP_MY_LOCK"
  59
  60         ...
  61
  62         if (_DtGetLock (display, MY_LOCK)) {
  63            <do whatever it is I want to do>
  64            _DtReleaseLock (display, MY_LOCK);
  65         }
  66         else {
  67            <do the alternative>
  68         }
  69 */
  70
  71 extern int _DtGetLock (
  72    Display *display,
  73    char  *lock_name);
  74 /*
  75     DESCRIPTION:
  76
  77         _DtGetLock attempts to get the specified lock.  If nobody holds
  78         the lock, _DtGetLock will obtain the lock and return 1.  If
  79         somebody else already holds the lock, the lock will not be
  80         disturbed and _DtGetLock will return 0.
  81
  82         If the process which owns a lock dies (or closes its X11 server
  83         connection), the lock will be automatically released.  To
  84         explicitly release a lock, use _DtReleaseLock.
  85
  86
  87     SYNOPSIS:
  88
  89         success = _DtGetLock (display, lock);
  90
  91         int success;            Returns 1 if the lock is obtained,
  92                                 0 if not.
  93
  94         Display *display;       The X11 server connection which will
  95                                 hold the lock.
  96
  97         char *lock;             The string which names the lock.
  98 */
  99
 100 extern void _DtReleaseLock (
 101    Display *display,
 102    char *lock_name);
 103 /*
 104     DESCRIPTION:
 105
 106         _DtReleaseLock releases a lock obtained by _DtGetLock.
 107
 108         WARNING!!  It is perfectly legal for one process to release
 109         a lock held by another process.  By convention you should only
 110         release locks previously obtained by your process from _DtGetLock
 111         unless you are playing God and know what you are doing.
 112
 113     SYNOPSIS:
 114
 115         (void) _DtReleaseLock (display, lock);
 116
 117         Display *display;       The X11 server connection which holds
 118                                 the lock.
 119
 120         char *lock;             The string which names the lock.
 121 */
 122
 123 extern int _DtTestLock (
 124    Display *display,
 125    char *lock_name);
 126 /*
 127     DESCRIPTION:
 128
 129         _DtTestLock returns a status indicating whether anybody holds the
 130         specified lock.
 131
 132     SYNOPSIS:
 133
 134         status = _DtTestLock (display, lock);
 135
 136         int success;            Returns 1 if anybody holds the lock,
 137                                 0 otherwise.
 138
 139         Display *display;       The X11 server connection.
 140
 141         char *lock;             The string which names the lock.
 142 */
 143
 144 #endif /* _Dt_lock_h */
 145 /* Do not add anything after this endif. */