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