Added information about new new ConverseInit
[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 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 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 initialization function
25 {\tt fn(argc, argv)} followed by the Converse scheduler.  Once the
26 scheduler exits on all processors, the Converse system shuts down, and
27 your program terminates.  Note that in this case, ConverseInit never
28 returns.  The user is not allowed to call the Converse scheduler
29 manually.
30
31 ConverseInit Returns Mode: {\tt initret=1}
32
33 This option is used when you want ConverseInit to return.  All
34 processors which automatically invoked {\tt main} must call
35 ConverseInit.  This initializes the entire Converse System.  On all
36 processors which {\em did not} automatically invoke main, Converse
37 initiates the user-supplied initialization function {\tt fn(argc,
38 argv)} followed by the Converse scheduler.  Meanwhile, on those
39 processors which {\em did} automatically invoke main, ConverseInit
40 returns.  Shutdown is initiated when the processors that {\em did}
41 automatically invoke main call ConverseExit, and when the other
42 processors exit the scheduler.  This option is not supported
43 by the sim version.
44
45 User Calls Scheduler Mode: {\tt usched=1}
46
47 This is how the user initializes charm if he wants to call the
48 Converse scheduler manually.  It is assumed that the user will call
49 the scheduler from inside the initialization function.  Thus,
50 ConverseInit will not automatically execute the scheduler for you.
51 This mode can be combined with ConverseInit returns mode.
52
53 \function{void ConverseExit(void)}
54 \index{ConverseExit}
55 \desc{This function is only used in ConverseInit returns mode, see
56 above.}
57