doc/converse/thsync.tex

   1
   2 \section{Synchronization Mechanisms}
   3 To use the following calls, include the file ``sync.h''
   4
   5 \subsection{Locks}
   6
   7 Locks (or mutexes) are synchronization mechanisms that can be used by user
   8 programs to provide mutual exclusion to critical sections. Threads that attempt
   9 to ``lock'' such a variable are suspended if the lock is already taken and are
  10 awakened when the lock becomes available to them.
  11
  12 \function{LOCK *CtsNewLock(void)}
  13 \desc{This call can be used to create a new lock variable.}
  14
  15 \function{CtsLockInit(LOCK *lock)}
  16 \desc{This call can be used to initialize a lock \param{lock} that was
  17 earlier allocated.}
  18
  19 \function{int CtsTryLock(LOCK *lock)}
  20 \desc{This call is a nonblocking attempt to lock \param{lock}. It returns
  21 1 immediately if \param{lock} is available after making the current thread
  22 \param{lock}'s owner and returns 0 if \param{lock} is already locked.}
  23
  24 \function{int CtsLock(LOCK *lock)}
  25 \desc{This call is used by a thread to wait until it obtains the ownership of
  26 \param{lock}. Several threads making this call may be queued up at the lock,
  27 which is then ``given'' to each in turn.}
  28
  29 \function{int CtsUnLock(LOCK *lock)}
  30 \desc{This call is used by a thread to relinquish the control of \param{lock}.
  31 An error value is returned if the thread attempts the unlock is not
  32 \param{lock}'s owner.}
  33
  34 \subsection{Condition Variables}
  35
  36 Condition variables are synchronization mechanisms that are used to implement
  37 trigger like functionality. Threads can wait on a condition variable. Other
  38 threads can either signal or broadcast this condition variable causing the
  39 awakening of either one or all of the threads waiting on this variable.
  40
  41 \function{CONDN *CtsNewCondn(void)}
  42 \desc{This call returns a new initialized condition variable.}
  43
  44 \function{int CtsCondnInit(CONDN *condn)}
  45 \desc{This call can be used to initialize a condition variable that was earlier
  46 allocated. This call causes all the waiting threads on this condition variable
  47 to be awakened.}
  48
  49 \function{int CtsCondnWait(CONDN *condn)}
  50 \desc{This call is used by thread that want to wait on the condition
  51 variable \param{condn}.}
  52
  53 \function{int CtsCondnSignal(CONDN *condn)}
  54 \desc{This call releases one of the threads waiting on the condition
  55 variable \param{condn}.}
  56
  57 \function{int CtsCondnBroadcast(CONDN *condn)}
  58 \desc{This call releases all the threads waiting on the condition variable
  59 \param{condn}.}
  60
  61 \subsection{Barriers}
  62 Barriers are a specialization of condition variables. A barrier is
  63 a condition variable whose {\em k}th wait is a broadcast for some initial k.
  64 That is, the barrier waits for k threads to reach a particular point before it
  65 lets them all go.
  66
  67 \function{BARRIER *CtsNewBarrier(void)}
  68 \desc{can be used to create a new barrier.}
  69
  70 \function{int CtsBarrierReinit(BARRIER *bar, int num)}
  71 \desc{This call (re)initializes the barrier \param{bar} to free any
  72 threads waiting on it and then to await the arrival of {\tt num} threads.}
  73
  74 \function{int CtsAtBarrier(BARRIER *bar)}
  75 \desc{Following the initialization of the barrier, the {\tt num} participating
  76 threads need to make this call before they can proceed beyond this point in
  77 the program. This call hence blocks all but the last thread to make this call,
  78 and awakens them all upon the arrival of this thread at the barrier.}
  79