*** empty log message ***
[charm.git] / doc / convext / pthreads.tex
1 \chapter{Converse-POSIX threads}
2
3 We have implemented the POSIX threads API on top of Converse threads.
4 To use the Converse-pthreads, you must include the header file:
5
6 \verb/#include <cpthreads.h>/
7
8 Refer to the POSIX threads documentation for the documentation on the
9 pthreads functions and types.  Although Converse-pthreads threads are
10 POSIX-compliant in most ways, there are some specific things one needs
11 to know to use our implementation.
12
13 \section{Pthreads and Converse}
14
15 Our pthreads implementation is designed to exist within a Converse
16 environment.  For example, to send messages inside a POSIX program,
17 you would still use the usual Converse messaging primitives.
18
19 \section{Suppressing Name Conflicts}
20
21 Some people may wish to use Converse pthreads on machines that already
22 have a pthreads implementation in the standard library.  This may
23 cause some name-conflicts as we define the pthreads functions, and the
24 system include files do too.  To avoid such conflicts, we provide an
25 alternative set of names beginning with the word Cpthread.  These
26 names are interchangable with their pthread equivalents.  In addition,
27 you may prevent Converse from defining the pthread names at all with
28 the preprocessor symbol SUPPRESS\_PTHREADS:
29
30 \begin{verbatim}
31 #define SUPPRESS_PTHREADS
32 #include <cpthreads.h>
33 \end{verbatim}
34
35 \section{Interoperating with Other Thread Packages}
36
37 Converse programs are typically multilingual programs.  There may be
38 modules written using POSIX threads, but other modules may use other
39 thread APIs.  The POSIX threads implementation has the following
40 restriction: you may only call the pthreads functions from inside
41 threads created with pthread\_create.  Threads created by other thread
42 packages (for example, the CthThread package) may not use the pthreads
43 functions.
44
45 \section{Preemptive Context Switching}
46
47 Most implementations of POSIX threads perform time-slicing: when a thread
48 has run for a while, it automatically gives up the CPU to another thread.
49 Our implementation is currently nonpreemptive (no time-slicing).  Threads
50 give up control at two points:
51
52 \begin{itemize}
53 \item{If they block (eg, at a mutex).}
54 \item{If they call pthread\_yield().}
55 \end{itemize}
56
57 Usually, the first rule is sufficient to make most programs work.
58 However, a few programs (particularly, those that busy-wait) may need
59 explicit insertion of yields.
60
61 \section{Limits on Blocking Operations in main}
62
63 Converse has a rule about blocking operations --- there are certain
64 pieces of code that may not block.  This was an efficiency decision.
65 In particular, the main function, Converse handlers, and the converse
66 startup function (see ConverseInit) may not block.  You must be aware
67 of this when using the POSIX threads functions with Converse.
68
69 There is a contradition here --- the POSIX standard requires that the
70 pthreads functions work from inside {\tt main}.  However, many of them
71 block, and Converse forbids blocking inside {\tt main}.  This
72 contradition can be resolved by renaming your posix-compliant {\tt
73 main} to something else: for example, {\tt mymain}.  Then, through the
74 normal Converse startup procedure, create a POSIX thread to run {\tt
75 mymain}.  We provide a convenience function to do this, called
76 Cpthreads\_start\_main.  The startup code will be much like this:
77
78 \begin{verbatim}
79 void mystartup(int argc, char **argv)
80 {
81   CpthreadModuleInit();
82   Cpthreads_start_main(mymain, argc, argv);
83 }
84
85 int main(int argc, char **argv)
86 {
87   ConverseInit(mystartup, argc, argv, 0, 0);
88 }
89 \end{verbatim}
90
91 This creates the first POSIX thread on each processor, which runs the
92 function mymain.  The mymain function is executing in a POSIX thread,
93 and it may use any pthread function it wishes.
94
95 \section{CpthreadModuleInit}
96
97 On each processor, the function CpthreadModuleInit must be called
98 before any other pthread function is called.  This is shown in the
99 example in the previous section.