doc/charm++/readonly.tex

   1 \section{Read-only Data}
   2 \label{readonly}
   3
   4 Since \charmpp\ does not allow global variables,
   5 it provides a special mechanism for sharing
   6 data amongst all objects. {\it Read-only} variables of simple data types or
   7 compound data types including messages and arrays are used to share information
   8 that is obtained only after the program begins execution and does not change
   9 after they are initialized in the dynamic scope of the {\tt main} function of
  10 the \kw{mainchare}. They are broadcast to every Charm++ Node (process) by the \charmpp\ runtime,
  11 and can be accessed in the same way as \CC ``global'' variables on any process.
  12 Compound data structures containing pointers can be made available as read-only
  13 variables using read-only messages(see section~\ref{messages}) or read-only arrays(see section~\ref{basic arrays}.  Note that memory
  14 has to be allocated for read-only messages by using \kw{new} to create the
  15 message in the {\tt main} function of the \kw{mainchare}.
  16
  17 Read-only variables are declared by using the type modifier \kw{readonly},
  18 which is similar to \kw{const} in \CC. Read-only data is specified in the {\tt
  19 .ci} file (the interface file) as:
  20
  21 \begin{alltt}
  22  readonly Type ReadonlyVarName;
  23 \end{alltt}
  24
  25 The variable \uw{ReadonlyVarName} is declared to be a read-only variable of
  26 type \uw{Type}. \uw{Type} must be a single token and not a type expression.
  27
  28 \begin{alltt}
  29  readonly message MessageType *ReadonlyMsgName;
  30 \end{alltt}
  31
  32 The variable \uw{ReadonlyMsgName} is declared to be a read-only message of type
  33 \uw{MessageType}. Pointers are not allowed to be readonly variables unless they
  34 are pointers to message types. In this case, the message will be initialized on
  35 every PE.
  36
  37 \begin{alltt}
  38  readonly Type ReadonlyArrayName [arraysize];
  39 \end{alltt}
  40
  41 The variable \uw{ReadonlyArrayName} is declared to be a read-only array of type
  42 \uw{Type} with \uw{arraysize} elements. \uw{Type} must be a single token and
  43 not a type expression. The value of \uw{arraysize} must be known at compile
  44 time.
  45
  46 Read-only variables must be declared either as global or as public class static
  47 data in the C/\CC\ implementation files, and these declarations have the usual
  48 form:
  49
  50 \begin{alltt}
  51  Type ReadonlyVarName;
  52  MessageType *ReadonlyMsgName;
  53  Type ReadonlyArrayName [arraysize];
  54 \end{alltt}
  55
  56 Similar declarations preceded by \kw{extern} would appear in the {\tt
  57 .h} file.
  58
  59 {\it Note:}  The current \charmpp\ translator cannot prevent
  60 assignments to read-only variables.  The user must make sure that no
  61 assignments occur in the program outside of the mainchare constructor.
  62
  63 For concrete examples for using read-only variables, please refer to examples
  64 such as \examplerefdir{array} and \examplerefdir{gaussSeidel3D}.
  65
  66 Users can get the same functionality of readonly variables by making such variables
  67 members of Charm++ Node Group objects and constructing the Node Group in the mainchare's
  68 main routine.
  69