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