73135e1fdd2cf1fc058cfdc204de1f550cbed912
[charm.git] / 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 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(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 are pointers to message types. In this case, the message will be initialized on
34 \uw{MessageType}. Pointers are not allowed to be readonly variables unless they
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{hello}, and GaussSeidel
66 elimination in \examplerefdir{gaussSeidel3D}.