hphp/neo/ulocks.h

   1 /*
   2  *
   3  * Thread-safe Skiplist Using Integer Identifiers
   4  * Copyright 1998-2000 Scott Shambarger (scott@shambarger.net)
   5  *
   6  * This software is open source. Permission to use, copy, modify, and
   7  * distribute this software for any purpose and without fee is hereby granted,
   8  * provided that the above copyright notice appear in all copies.  No
   9  * warranty of any kind is expressed or implied.  Use at your own risk.
  10  *
  11  * 1/14/2001 blong
  12  *   Made it use neo errs... probably need to check locking functions
  13  *   for error returns...
  14  *
  15  */
  16
  17 #ifndef incl_HPHP_ULOCKS_H_
  18 #define incl_HPHP_ULOCKS_H_
  19
  20
  21 NEOERR *fCreate(int *plock, const char *file);
  22 /*
  23  * Function:    fCreate - create a file lock.
  24  * Description: Creates a file lock on named file <file>.  The lock is
  25  *              returned in <plock>.
  26  * Input:       plock - place for lock.
  27  *              file - path of file to use as lock.
  28  * Output:      plock - set to lock identifier.
  29  * Return:      STATUS_OK on success
  30  *              NERR_IO on failure
  31  * MT-Level:    Safe.
  32  */
  33
  34 NEOERR *fFind(int *plock, const char *file);
  35 /*
  36  * Function:    fFind - find a file lock.
  37  * Description: Find a file identified by the path <file>, and returns a
  38  *              lock identifier for it in <plock>.  If the file doesn't
  39  *              exist, returns true.
  40  * Input:       plock - place for lock.
  41  *              file - path of file to use as lock.
  42  * Output:      plock - set to lock identifier.
  43  * Return:      STATUS_OK if found
  44  *              NERR_IO on failure
  45  * MT-Level:    Safe.
  46  */
  47
  48 void fDestroy(int lock);
  49 /*
  50  * Function:    fDestroy - destroy a lock.
  51  * Description: Destroys the lock <lock> that was created by fCreate()
  52  *              or fFind().
  53  * Input:       lock - Lock to destroy.
  54  * Output:      None.
  55  * Return:      None.
  56  * MT-Level:    Safe for unique <lock>.
  57  */
  58
  59 NEOERR *fLock(int lock);
  60 /*
  61  * Function:    fLock - acquire file lock.
  62  * Description: Acquires the lock identified by <lock>.  This call
  63  *              blocks until the lock is acquired.
  64  * Input:       lock - Lock to acquire.
  65  * Output:      None.
  66  * Return:      STATUS_OK on success
  67  *              NERR_LOCK on failure
  68  * MT-Level:    Safe.
  69  */
  70
  71 void fUnlock(int lock);
  72 /*
  73  * Function:    fUnlock - release file lock.
  74  * Description: Releases the lock identified by <lock>.
  75  * Input:       lock - Lock to release.
  76  * Output:      None.
  77  * Return:      None.
  78  * MT-Level:    Safe.
  79  */
  80
  81 #ifdef HAVE_PTHREADS
  82
  83 #include <pthread.h>
  84
  85
  86 NEOERR *mCreate(pthread_mutex_t *mutex);
  87 /*
  88  * Function:    mCreate - initialize a mutex.
  89  * Description: Initializes the mutex <mutex>.
  90  * Input:       mutex - mutex to initialize.
  91  * Output:      None.
  92  * Return:      STATUS_OK on success
  93  *              NERR_LOCK on failure
  94  * MT-Level:    Safe for unique <mutex>.
  95  */
  96
  97 void mDestroy(pthread_mutex_t *mutex);
  98 /*
  99  * Function:    mDestroy - destroy a mutex.
 100  * Description: Destroys the mutex <mutex> that was initialized by mCreate().
 101  * Input:       mutex - mutex to destroy.
 102  * Output:      None.
 103  * Return:      None.
 104  * MT-Level:    Safe for unique <mutex>.
 105  */
 106
 107 NEOERR *mLock(pthread_mutex_t *mutex);
 108 /*
 109  * Function:    mLock - lock a mutex.
 110  * Description: Locks the mutex <mutex>.  This call blocks until the mutex
 111  *              is acquired.
 112  * Input:       mutex - mutex to lock.
 113  * Output:      None.
 114  * Return:      STATUS_OK on success
 115  *              NERR_LOCK on failure
 116  * MT-Level:    Safe.
 117  */
 118
 119 NEOERR *mUnlock(pthread_mutex_t *mutex);
 120 /*
 121  * Function:    mUnlock - unlock a mutex.
 122  * Description: Unlocks the mutex <mutex>.
 123  * Input:       mutex - mutex to unlock.
 124  * Output:      None.
 125  * Return:      STATUS_OK on success
 126  *              NERR_LOCK on failure
 127  * MT-Level:    Safe.
 128  */
 129
 130 NEOERR *cCreate(pthread_cond_t *cond);
 131 /*
 132  * Function:    cCreate - initialize a condition variable.
 133  * Description: Initializes the condition variable <cond>.
 134  * Input:       cond - condition variable to initialize.
 135  * Output:      None.
 136  * Return:      STATUS_OK on success
 137  *              NERR_LOCK on failure
 138  * MT-Level:    Safe for unique <cond>.
 139  */
 140
 141 void cDestroy(pthread_cond_t *cond);
 142 /*
 143  * Function:    cDestroy - destroy a condition variable.
 144  * Description: Destroys the condition variable <cond> that was
 145  *              initialized by cCreate().
 146  * Input:       cond - condition variable to destroy.
 147  * Output:      None.
 148  * Return:      None.
 149  * MT-Level:    Safe for unique <cond>.
 150  */
 151
 152 NEOERR *cWait(pthread_cond_t *cond, pthread_mutex_t *mutex);
 153 /*
 154  * Function:    cWait - wait a condition variable signal.
 155  * Description: Waits for a signal on condition variable <cond>.
 156  *              The mutex <mutex> must be locked by the thread.
 157  * Input:       cond - condition variable to wait on.
 158  *              mutex - locked mutex to protect <cond>.
 159  * Output:      None.
 160  * Return:      STATUS_OK on success
 161  *              NERR_LOCK on failure
 162  * MT-Level:    Safe.
 163  */
 164
 165 NEOERR *cBroadcast(pthread_cond_t *cond);
 166 /*
 167  * Function:    cBroadcast - broadcast signal to all waiting threads.
 168  * Description: Broadcasts a signal to all threads waiting on condition
 169  *              variable <cond>.
 170  * Input:       cond - condition variable to broadcast on.
 171  * Output:      None.
 172  * Return:      STATUS_OK on success
 173  *              NERR_LOCK on failure
 174  * MT-Level:    Safe.
 175  */
 176
 177 NEOERR *cSignal(pthread_cond_t *cond);
 178 /*
 179  * Function:    cSignal - send signal to one waiting thread.
 180  * Description: Sends a signal to one thread waiting on condition
 181  *              variable <cond>.
 182  * Input:       cond - condition variable to send signal on.
 183  * Output:      None.
 184  * Return:      STATUS_OK on success
 185  *              NERR_LOCK on failure
 186  * MT-Level:    Safe.
 187  */
 188
 189 #endif /* HAVE_PTHREAD */
 190
 191 #endif                                                       /* incl_HPHP_ULOCKS_H_ */