doc/charm++: startup text revisions
[charm.git] / 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