c87a1e595c02be85802d2293a82f68a6a181efdf
[charm.git] / doc / converse / usermain.tex
1 \chapter{Initialization and Completion}
2
3 The program utilizing Converse begins executing at {\tt main}, like
4 any other C program.  However, depending on the machine and the
5 implementation decisions of the machine's vendor, {\tt main} may be
6 executed by more than one processor.  On some machines, every
7 processor executes {\tt main}.  On others, only one processor executes
8 {\tt main}.  All processors which don't execute {\tt main} are asleep
9 when the program begins.
10
11 There are two ways for the program to start up the Converse system.
12 The first method is to use ConverseInit:
13
14 \function{typedef void (*CmiStartFn)(int argc, char **argv);}
15 \function{void ConverseInit(int argc, char *argv[], CmiStartFn fn)}
16 \index{ConverseInit}
17 \desc{This must be called by every processor which initially executed
18 {\tt main}.  Initializes the entire Converse system, then causes all
19 processors to begin executing the function {\tt fn}, which should
20 perform all your computation.  ConverseInit never returns.  You may
21 not call any other Converse function until initialization is complete,
22 that is, until {\tt fn} begins executing. \param{argc} and
23 \param{argv} are in the same format as the arguments passed to
24 \param{main(argc, argv)}.}
25
26 ConverseInit is the initialization method one would use in most
27 programs.  However, some programs may find it difficult to work around
28 the constraint that ConverseInit never returns.  Thus, we provide
29 ConverseStart, an alternate initialization method.  Currently,
30 ConverseStart is supported on all machines, however, it is {\em
31 potentially} possible that it will be unimplementable on some
32 machines.  Thus, we do not guarantee its presence.  Use it only when
33 you absolutely need a startup function that returns.
34
35 \function{void ConverseStart(int argc, char *argv[], CmiStartFn fn)}
36 \index{ConverseInit}
37 \desc{This must be called by every processor which initially executed
38 {\tt main}.  Initializes the entire Converse system, then causes all
39 processors {\em which did not initially execute {\tt main}} to begin
40 executing the function {\tt fn}.  Once these threads have been
41 launched, ConverseStart returns.  You may not call any other Converse
42 function until initialization is complete, that is, until {\tt fn}
43 begins executing and ConverseStart returns. \param{argc} and
44 \param{argv} are in the same format as the arguments as passed to
45 \param{main(argc, argv)}.}
46
47 Regardless which startup method is used, all processors should call
48 ConverseExit during termination:
49
50 \function{void ConverseExit(void)}
51 \index{ConverseExit}
52 \desc{This function frees the resources acquired by Converse and wraps up. 
53 Any other Converse function should not be called after a call to this
54 function.}
55