0c9d6d93442b5700cb49965bfc825efbba1c021b
[charm.git] / doc / charm++ / readonly.tex
1 \section{Read-only Variables, Messages and Arrays}
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 PE by the \charmpp\ runtime,
11 and can be accessed in the same way as \CC ``global'' variables on any PE.
12 Compound data structures containing pointers can be made available as read-only
13 variables using read-only messages or read-only 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 Travelling
64 Salesman Problem (TSP) in
65 \examplerefdir{state\_space\_searchengine/TSP\_SE}, and GaussSeidel
66 elimination in \examplerefdir{gaussSeidel3D}.