\chapter{Initialization and Completion}
\label{initial}

The program utilizing \converse{} begins executing at {\tt main}, like
any other C program.  The initialization process is somewhat
complicated by the fact that hardware vendors don't agree about which
processors should execute {\tt main}.  On some machines, every processor
executes {\tt main}.  On others, only one processor executes {\tt
main}.  All processors which don't execute {\tt main} are asleep when
the program begins.  The function ConverseInit is used to start the
\converse{} system, and to wake up the sleeping processors.

\function{typedef void (*CmiStartFn)(int argc, char **argv);}
\function{void ConverseInit(int argc, char *argv[], CmiStartFn fn, int usched, int initret)}
\index{ConverseInit}
\desc{This function starts up the \converse{} system.  It can execute
in one of the modes described below.

Normal Mode: {\tt schedmode=0, initret=0}

When the user runs a program, some of the processors automatically invoke
{\tt main}, while others remain asleep.  All processors which automatically
invoked {\tt main} must call ConverseInit.  This initializes the
entire \converse{} system.  \converse{} then initiates, on {\em all}
processors, the execution of the user-supplied start-function {\tt
fn(argc, argv)}.  When this function returns, \converse{} automatically
calls {\tt CsdScheduler}, a function that polls for messages and
executes their handlers (see chapter 2).  Once {\tt CsdScheduler}
exits on all processors, the \converse{} system shuts down, and the user's
program terminates.  Note that in this case, ConverseInit never
returns.  The user is not allowed to poll for messages manually.

User-calls-scheduler Mode: {\tt schedmode=1, initret=0}

If the user wants to poll for messages and other events manually, this
mode is used to initialize \converse{}.  In normal mode, it is assumed
that the user-supplied start-function {\tt fn(argc, argv)} is just for
initialization, and that the remainder of the lifespan of the program
is spent in the (automatically-invoked) function {\tt CsdScheduler},
polling for messages.  In user-calls-scheduler mode, however, it is
assumed that the user-supplied start-function will perform the {\em
entire computation}, including polling for messages.  Thus,
ConverseInit will not automatically call {\tt CsdScheduler} for you.
When the user-supplied start-function ends, \converse{} shuts down.  This
mode is not supported on the sim version.  This mode can be combined
with ConverseInit-returns mode below.}

ConverseInit-returns Mode: {\tt schedmode=1, initret=1}

This option is used when you want ConverseInit to return.  All
processors which automatically invoked {\tt main} must call
ConverseInit.  This initializes the entire \converse{} System.  On all
processors which {\em did not} automatically invoke {\tt main},
\converse{} initiates the user-supplied initialization function {\tt
fn(argc, argv)}.  Meanwhile, on those processors which {\em did}
automatically invoke {\tt main}, ConverseInit returns.  Shutdown is
initiated when the processors that {\em did} automatically invoke {\tt
main} call ConverseExit, and when the other processors return from
{\tt fn}.  In this mode, all polling for messages must be done
manually (probably using CsdScheduler explicitly).  This option is not
supported by the sim version.

\function{void ConverseExit(void)}
\index{ConverseExit}
\desc{This function is only used in ConverseInit-returns mode, described
above.}

\function{void CmiAbort(char *msg)}
\index{CmiAbort}
\desc{This function can be used portably to abnormally terminate a \converse{}
  program. Before termination, it prints a message supplied as {\tt msg}.}


\function{void CmiAssert(int expr)}
\index{CmiAssert}
\desc{This macro terminates the Converse program after printing an informative
 message if \texttt{expr} evaluates to 0. It can be used in place of 
 \texttt{assert}. In order to turn off \texttt{CmiAssert}, one should define
 $CMK\_OPTIMIZE$ as 1.}
