doc: dont refer to dead section
[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.
7
8 \function{void CkAssert(int expression)} \desc{Aborts the program 
9 if expression is 0.}
10
11 \function{void CkAbort(const char *message)} \index{CkAbort}
12 \desc{Causes the program to abort, printing the given error message.
13   This function never returns.}
14
15 \function{void CkExit()} \index{CkExit} \desc{This call informs the
16   Charm RTS that computation on all processors should terminate.  This
17   routine never returns, so any code after the call to CkExit() inside
18   the function that calls it will not execute. Other processors will
19   continue executing until they receive notification to stop, so it is
20   a good idea to ensure through synchronization that all useful work
21   has finished before calling CkExit().  }
22
23 \function{double CkWallTimer()} \index{CkWallTimer} \index{timers}
24 \desc{Returns the elapsed time in seconds since the start of the program.}
25
26 \subsection{Information about Logical Machine Entities}
27 As described in section~\ref{machineModel}, \charmpp{} recoginizes two
28 logical machine entities: ``node'' and PE (processing element). 
29 The following functions provide basic information about such logical machine 
30 that a \charmpp{} program runs on. PE and ``node'' are numbered starting
31 from zero.
32
33 \function{int CkNumPes()} \index{CkNumPes} \desc{returns the total
34   number of PEs across all nodes.}
35
36 \function{int CkMyPe()} \index{CkMyPe} \desc{returns the index of the
37   PE on which the call was made.}
38
39 \function{int CkNumNodes()} \index{CkMyNodes}
40 \desc{returns the total number of logical \charmpp{} nodes.}
41
42 \function{int CkMyNode()} \index{CkMyNode}
43 \desc{returns the index of the ``node'' on which the call was made.}
44
45 \function{int CkMyRank()} \index{CkMyRank}
46 \desc{returns the rank number of the PE on a ``node'' on which the call 
47 was made. PEs within a ``node'' are also ranked starting from zero.}
48
49 \function{int CkNodeFirst(int nd)} \index{CkNodeFirst}
50 \desc{returns the index of the first PE on the logical node $nd$.}
51
52 \function{int CkNodeSize(int nd)} \index{CkNodeSize}
53 \desc{returns the number of PEs on the logical node $nd$ on which the call was made.}
54
55 \function{int CkNodeOf(int pe)} \index{CkNodeOf}
56 \desc{returns the ``node'' number that PE $pe$ belongs to.}
57
58 \function{int CkRankOf(int pe)} \index{CkRankOf}
59 \desc{returns the rank of the given PE within its node.}
60
61 \subsection{Terminal I/O}
62
63 \index{input/output}
64 \charmpp\ provides both C and \CC\ style methods of doing terminal I/O.  
65
66 In place of C-style printf and scanf, \charmpp\ provides
67 \kw{CkPrintf} and \kw{CkScanf}.  These functions have
68 interfaces that are identical to their C counterparts, but there are some
69 differences in their behavior that should be mentioned.
70
71 \charmpp\ also supports all forms of printf,
72 cout, etc. in addition to the special forms shown below.  The special
73 forms below are still useful, however, since they obey well-defined
74 (but still lax) ordering requirements.
75
76 \function{int CkPrintf(format [, arg]*)} \index{CkPrintf}
77 \index{input/output} \desc{This call is used for atomic terminal
78   output. Its usage is similar to \texttt{printf} in C.  However,
79   \kw{CkPrintf} has some special properties that make it more suited
80   for parallel programming.  \kw{CkPrintf} routes all terminal output
81   to a single end point which prints the output. This guarantees that
82   the output for a single call to CkPrintf will be printed completely
83   without being interleaved with other calls to CkPrintf. Note that
84   CkPrintf is implemented using an asynchronous send, meaning that the
85   call to \kw{CkPrintf} returns immediately after the message has been
86   sent, and most likely before the message has actually been received,
87   processed, and displayed. As such, there is no guarantee of order in
88   which the output for concurrent calls to CkPrintf is
89   printed. Imposing such an order requires proper synchronization
90   between the calls to CkPrintf in the parallel application.
91 }
92
93 \function{void CkError(format [, arg]*))} \index{CkError} \index{input/output} 
94 \desc{Like \kw{CkPrintf}, but used to print error messages on \texttt{stderr}.}
95
96 \function{int CkScanf(format [, arg]*)} \index{CkScanf} \index{input/output}
97 \desc{This call is used for atomic terminal input. Its usage is similar to
98 {\tt scanf} in C.  A call to \kw{CkScanf}, unlike \kw{CkPrintf},
99 blocks all execution on the processor it is called from, and returns
100 only after all input has been retrieved.
101 }
102
103 For \CC\ style stream-based I/O, \charmpp\ offers 
104 \kw{ckout} and \kw{ckerr} in place of cout and cerr.  The
105 \CC\ streams and their \charmpp\ equivalents are related in the same
106 manner as printf and scanf are to \kw{CkPrintf} and \kw{CkScanf}.  The
107 \charmpp\ streams are all used through the same interface as the \CC\ 
108 streams, and all behave in a slightly different way, just like C-style
109 I/O.