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