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{} recognizes 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.