R-arrays

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 in, inout, or out 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 NULL as a normal SIDL array.

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.

R-arrays are have more restrictions in how they can be used. Here is how r-arrays are more constrainted:

  1. Only the in and inout parameter modes are available for r-arrays. R-arrays cannot be used as return values or as out parameters.
  2. R-arrays must be contiguous in memory, and multi-dimensional arrays must be in column-major order (i.e., Fortran order).
  3. NULL is not an allowable value for an r-array parameter.
  4. The semantics for inout r-array parameters are different. The implementation is not allowed to deallocate the array and return a new r-array. inout 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.
  5. The implementation of a method taking an r-array parameter cannot change the shape of the array.
  6. The lower index is always 0, and the upper index is $n-1$ where $n$ is the length in a particular dimension. This is contrary to the normal convention for Fortran arrays.
  7. It can only be used for arrays of SIDL int, long, float, double, fcomplex, and dcomplex types.

\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}
The advantages of r-arrays include:

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, $A x = b$:

    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);
In this example, A is a 2-D array of doubles with m rows and n columns. x is a 1-D array of doubles of length n, and b is a 1-D array of doubles of length m. 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 A, x and b 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.

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.



babel-0.10.2
users_guide Last Modified 2005-03-23

http://www.llnl.gov/CASC/components
components@llnl.gov