R-arrays

Since SIDL was designed to serve the high performance computing community, both SIDL object developers and clients may require direct access to the underlying array data structure for optimization purposes, such as instruction pipelining or cache performance. Hence, support for raw SIDL arrays was introduced for low level access to numeric arrays. At present, they are limited use in C, C++, FORTRAN 77, and Fortran 90.

Unlike normal SIDL arrays, the use of r-arrays are more restricted. More specifically, they have the following constraints$:$

  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-1.4.0
users_guide Last Modified 2008-10-16

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