Just trying to make this whole manual make more sense.
[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.  The initialization process is somewhat
5 complicated by the fact that vendors don't agree about which
6 processors should execute {\tt main}.  On some machines, every processor
7 executes {\tt main}.  On others, only one processor executes {\tt
8 main}.  All processors which don't execute {\tt main} are asleep when
9 the program begins.  The function ConverseInit is used to start the
10 converse system, and to wake up the sleeping processors:
11
12 \function{typedef void (*CmiStartFn)(int argc, char **argv);}
13 \function{void ConverseInit(int argc, char *argv[], CmiStartFn fn, int usched, int initret)}
14 \index{ConverseInit}
15 \desc{This function starts up the Converse system.  It can execute
16 in one of several modes, described below.
17
18 Normal Mode: {\tt usched=0, initret=0}
19
20 When you run your program, some of the processors automatically invoke
21 {\tt main}, others remain asleep.  All processors which automatically
22 invoked {\tt main} must must call ConverseInit.  This initializes the
23 entire Converse system.  Converse then initiates, on {\em all}
24 processors, the execution of the user-supplied start-function {\tt
25 fn(argc, argv)}.  When this function returns, Converse automatically
26 calls {\tt CsdScheduler}, a function that polls for messages and
27 executes their handlers (see chapter 2).  Once {\tt CsdScheduler}
28 exits on all processors, the Converse system shuts down, and your
29 program terminates.  Note that in this case, ConverseInit never
30 returns.  The user is not allowed to poll for messages manually.
31
32 User-calls-scheduler Mode: {\tt usched=1, initret=0}
33
34 This is how the user initializes Converse if he wants to poll for
35 messages and other events manually.  In normal mode, it is assumed
36 that the user-supplied start-function {\tt fn(argc, argv)} is just for
37 initialization, and that the remainder of the lifespan of the program
38 is spent in the (automatically-invoked) function {\tt CsdScheduler},
39 polling for messages.  In user-calls-scheduler mode, however, it is
40 assumed that the user-supplied start-function will perform the {\em
41 entire computation}, including polling for messages.  Thus,
42 ConverseInit will not automatically call {\tt CsdScheduler} for you.
43 When the user-supplied start-function ends, Converse shuts down.  This
44 mode is not supported on the sim version.  This mode can be combined
45 with ConverseInit returns mode below.}
46
47 ConverseInit-returns Mode: {\tt usched=1, initret=1}
48
49 This option is used when you want ConverseInit to return.  All
50 processors which automatically invoked {\tt main} must call
51 ConverseInit.  This initializes the entire Converse System.  On all
52 processors which {\em did not} automatically invoke {\tt main},
53 Converse initiates the user-supplied initialization function {\tt
54 fn(argc, argv)}.  Meanwhile, on those processors which {\em did}
55 automatically invoke {\tt main}, ConverseInit returns.  Shutdown is
56 initiated when the processors that {\em did} automatically invoke {\tt
57 main} call ConverseExit, and when the other processors return from
58 {\tt fn}.  In this mode, all polling for messages must be done
59 manually (probably using CsdScheduler explicitly).  This option is not
60 supported by the sim version.
61
62 \function{void ConverseExit(void)}
63 \index{ConverseExit}
64 \desc{This function is only used in ConverseInit returns mode, see
65 above.}
66