1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>R-arrays</TITLE>
<META NAME="description" CONTENT="R-arrays">
<META NAME="keywords" CONTENT="users_guide">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="users_guide.css">
<LINK REL="next" HREF="node61.html">
<LINK REL="previous" HREF="node59.html">
<LINK REL="up" HREF="node59.html">
<LINK REL="next" HREF="node61.html">
</HEAD>
<BODY >
<DIV CLASS="navigation"><!--Navigation Panel-->
<A NAME="tex2html1552"
HREF="node61.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html1546"
HREF="node59.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html1540"
HREF="node59.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html1548"
HREF="node14.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html1550"
HREF="node317.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1553"
HREF="node61.html">SIDL Language Features</A>
<B> Up:</B> <A NAME="tex2html1547"
HREF="node59.html">Arrays</A>
<B> Previous:</B> <A NAME="tex2html1541"
HREF="node59.html">Arrays</A>
<B> <A NAME="tex2html1549"
HREF="node14.html">Contents</A></B>
<B> <A NAME="tex2html1551"
HREF="node317.html">Index</A></B>
<BR>
<BR></DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION02441000000000000000"></A>
<A NAME="ss:r-arrays"></A>
<BR>
R-arrays
</H2>
<P>
There are two kinds of SIDL arrays: normal SIDL arrays and raw SIDL
arrays called r-arrays. Normal SIDL arrays provide all the features of
a normal SIDL type. They can be passed as <TT>in</TT>, <TT>inout</TT>, or
<TT>out</TT> parameters, and they can be returned as a method return
value. Normal SIDL arrays can be allocated or borrowed, and they are
reference counted. You can also pass <TT>NULL</TT> as a normal SIDL
array.
<P>
SIDL r-arrays exist to provide a lower access to numeric arrays from
C, C++, Fortran 77, Fortran 90 and future languages as
appropriate. For example, a one-dimensional r-array in C appears as a
double pointer and a length parameter. To highlight the contrast,
normal SIDL arrays appear as a struct in C, a template class in C++,
an 64-bit integer in Fortran 77 and a derived type in Fortran 90.
<P>
R-arrays are have more restrictions in how they can be used. Here is
how r-arrays are more constrainted:
<OL>
<LI>Only the <TT>in</TT> and <TT>inout</TT> parameter modes are
available for r-arrays. R-arrays cannot be used as return values or as
<TT>out</TT> parameters.
</LI>
<LI>R-arrays must be contiguous in memory, and multi-dimensional
arrays must be in column-major order (i.e., Fortran order).
</LI>
<LI><TT>NULL</TT> is not an allowable value for an r-array parameter.
</LI>
<LI>The semantics for <TT>inout</TT> r-array parameters are
different. The implementation is not allowed to deallocate the array
and return a new r-array. <TT>inout</TT> means that the array data is
transferred from caller to callee at the start of a method
invocation and from callee to caller at the end of the a method
invocation.
</LI>
<LI>The implementation of a method taking an r-array parameter
cannot change the shape of the array.
</LI>
<LI>The lower index is always 0, and the upper index is <SPAN CLASS="MATH"><IMG
WIDTH="40" HEIGHT="29" ALIGN="MIDDLE" BORDER="0"
SRC="img13.png"
ALT="$n-1$"></SPAN> where
<SPAN CLASS="MATH"><IMG
WIDTH="13" HEIGHT="13" ALIGN="BOTTOM" BORDER="0"
SRC="img14.png"
ALT="$n$"></SPAN> is the length in a particular dimension. This is contrary to the
normal convention for Fortran arrays.
</LI>
<LI>It can only be used for arrays of SIDL <TT>int</TT>, <TT>long</TT>,
<TT>float</TT>, <TT>double</TT>, <TT>fcomplex</TT>, and <TT>dcomplex</TT> types.
</LI>
</OL>
<BR>
<IMG
WIDTH="477" HEIGHT="119" ALIGN="BOTTOM" BORDER="0"
SRC="img15.png"
ALT="\begin{rationale}
The way r-arrays are passed to the server-side code, particula...
...e languages characters are treated as 16-bit Unicode characters.
\end{rationale}">
<BR>
The advantages of r-arrays include:
<UL>
<LI>Arrays appear more ``natural'' in C, C++, Fortran 77, Fortran 90 and
future low level languages.
</LI>
<LI>Developers need less or no code to tranlate between their array
data structure and SIDL's array data structure.
</LI>
<LI>SIDL generated APIs can have signatures very similar if not
identical to well known legacy APIs.
</LI>
<LI>Less performance overhead because r-arrays can avoid a call to
<TT>malloc</TT> and <TT>free</TT>.
</LI>
</UL>
<P>
When you declare an r-array, you also declare the index variables that
will hold the size of the array in each dimension. For example, here
is an method to solve one of the fundamental problems of linear
algebra, <SPAN CLASS="MATH"><IMG
WIDTH="52" HEIGHT="14" ALIGN="BOTTOM" BORDER="0"
SRC="img16.png"
ALT="$A x = b$"></SPAN>:
<BR>
<PRE CLASS="verbatim"> void solve(in rarray<double,2> A(m,n),
inout rarray<double> x(n),
in rarray<double> b(m),
in int m,
in int n);
</PRE></td></tr></table></blockquote>In this example, <TT>A</TT> is a 2-D array of doubles with <TT>m</TT> rows
and <TT>n</TT> columns. <TT>x</TT> is a 1-D array of doubles of length
<TT>n</TT>, and <TT>b</TT> is a 1-D array of doubles of length
<TT>m</TT>. Note that by explicitly declaring the index variables, SIDL
takes avoid using extra array size parameters by taking advantage of
the fact that the sizes of <TT>A</TT>, <TT>x</TT> and <TT>b</TT> are all
inter-related. The explicit declaration also allows the developer to
control where the index parameters appear in the argument list. In
many cases, the argument types and order can match existing APIs.
<P>
The mapping for the solve method will be shown for C, C++, Fortran 77
and Fortran 90 in the following chapters. In languages that do not
support low level access such as Python and Java, r-arrays are treated
just like normal SIDL arrays, and the redundant index arguments are
dropped from the argument list. The indexing information is available
from the SIDL array data structure.
<P>
<DIV CLASS="navigation"><HR>
<!--Navigation Panel-->
<A NAME="tex2html1552"
HREF="node61.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html1546"
HREF="node59.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html1540"
HREF="node59.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html1548"
HREF="node14.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html1550"
HREF="node317.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1553"
HREF="node61.html">SIDL Language Features</A>
<B> Up:</B> <A NAME="tex2html1547"
HREF="node59.html">Arrays</A>
<B> Previous:</B> <A NAME="tex2html1541"
HREF="node59.html">Arrays</A>
<B> <A NAME="tex2html1549"
HREF="node14.html">Contents</A></B>
<B> <A NAME="tex2html1551"
HREF="node317.html">Index</A></B> </DIV>
<!--End of Navigation Panel-->
<ADDRESS>
<br><br>babel-0.10.2<br>users_guide Last Modified 2005-03-23<br><br><a href="http://www.llnl.gov/CASC/components">http://www.llnl.gov/CASC/components</a><br><a href="mailto:components@llnl.gov">components@llnl.gov</a>
</ADDRESS>
</BODY>
</HTML>
|
