e0ff830852cc4e8e7af675241674371d8c98cc59
[charm.git] / doc / charm++ / utilities.tex
1 \section{Utility Functions}
2
3 \label{basic utility fns}
4
5 The following calls provide basic rank information and utilities
6 useful when running a Charm++ program. Other utilities are listed in
7 Section~\ref{other Charm++ calls}.
8
9 \function{int CkNumPes()} \index{CkNumPes} \desc{returns the total
10   number of processing elements (PEs), across all nodes.}
11
12 \function{int CkMyPe()} \index{CkMyPe} \desc{returns the index of the
13   PE on which the call was made.}
14
15 \function{void CkAssert(int expression)} \desc{Aborts the program 
16 if expression is 0.}
17
18 \function{void CkAbort(const char *message)} \index{CkAbort}
19 \desc{Causes the program to abort, printing the given error message.
20   This function never returns.}
21
22 \function{void CkExit()} \index{CkExit} \desc{This call informs the
23   Charm RTS that computation on all processors should terminate.  This
24   routine never returns, so any code after the call to CkExit() inside
25   the function that calls it will not execute. Other processors will
26   continue executing until they receive notification to stop, so it is
27   a good idea to ensure through synchronization that all useful work
28   has finished before calling CkExit().  }
29
30 \function{double CkWallTimer()} \index{CkWallTimer} \index{timers}
31 \desc{Returns the elapsed time in seconds since the start of the program.}
32
33 \subsection{Terminal I/O}
34
35 \index{input/output}
36 \charmpp\ provides both C and \CC\ style methods of doing terminal I/O.  
37
38 In place of C-style printf and scanf, \charmpp\ provides
39 \kw{CkPrintf} and \kw{CkScanf}.  These functions have
40 interfaces that are identical to their C counterparts, but there are some
41 differences in their behavior that should be mentioned.
42
43 \charmpp\ also supports all forms of printf,
44 cout, etc. in addition to the special forms shown below.  The special
45 forms below are still useful, however, since they obey well-defined
46 (but still lax) ordering requirements.
47
48 \function{int CkPrintf(format [, arg]*)} \index{CkPrintf}
49 \index{input/output} \desc{This call is used for atomic terminal
50   output. Its usage is similar to \texttt{printf} in C.  However,
51   \kw{CkPrintf} has some special properties that make it more suited
52   for parallel programming.  \kw{CkPrintf} routes all terminal output
53   to a single end point which prints the output. This guarantees that
54   the output for a single call to CkPrintf will be printed completely
55   without being interleaved with other calls to CkPrintf. Note that
56   CkPrintf is implemented using an asynchronous send, meaning that the
57   call to \kw{CkPrintf} returns immediately after the message has been
58   sent, and most likely before the message has actually been received,
59   processed, and displayed. As such, there is no guarantee of order in
60   which the output for concurrent calls to CkPrintf is
61   printed. Imposing such an order requires proper synchronization
62   between the calls to CkPrintf in the parallel application.
63 }
64
65 \function{void CkError(format [, arg]*))} \index{CkError} \index{input/output} 
66 \desc{Like \kw{CkPrintf}, but used to print error messages on \texttt{stderr}.}
67
68 \function{int CkScanf(format [, arg]*)} \index{CkScanf} \index{input/output}
69 \desc{This call is used for atomic terminal input. Its usage is similar to
70 {\tt scanf} in C.  A call to \kw{CkScanf}, unlike \kw{CkPrintf},
71 blocks all execution on the processor it is called from, and returns
72 only after all input has been retrieved.
73 }
74
75 For \CC\ style stream-based I/O, \charmpp\ offers 
76 \kw{ckout} and \kw{ckerr} in place of cout and cerr.  The
77 \CC\ streams and their \charmpp\ equivalents are related in the same
78 manner as printf and scanf are to \kw{CkPrintf} and \kw{CkScanf}.  The
79 \charmpp\ streams are all used through the same interface as the \CC\ 
80 streams, and all behave in a slightly different way, just like C-style
81 I/O.