Mapping for classes, interfaces, arrays and r-arrays

Because C doesn't have built in mechanisms for protecting the global namespace, the C mapping attempts to avoid namespace collisions by using struct and method names that incorporate all the naming information from the package, class and method names. Without this approach, there would be multiple structures or functions with the same name which would cause compile and link errors. For a type Z in package X.Y, the name of the type that C clients use for an object reference is X_Y_Z. X_Y_Z is defined as follows in the X_Y_Z.h header file:


struct X_Y_Z__object;
struct X_Y_Z__array;
typedef struct X_Y_Z__object* X_Y_Z;

This code fragment also shows that struct X_Y_Z__array is used for a multi-dimensional array of X.Y.Z objects. Here are some additional concrete examples of the object and interface reference types derived by the C mapping:


/**
 * Symbol "sidl.BaseClass" (version 0.9.12)
 * 
 * Every class implicitly inherits from <code>BaseClass</code>.  This
 * class implements the methods in <code>BaseInterface</code>.
 */
struct sidl_BaseClass__object;
struct sidl_BaseClass__array;
typedef struct sidl_BaseClass__object* sidl_BaseClass;

/**
 * Symbol "sidl.BaseInterface" (version 0.9.12)
 * 
 * Every interface in <code>SIDL</code> implicitly inherits
 * from <code>BaseInterface</code>, and it is implemented
 * by <code>BaseClass</code> below.
 */
struct sidl_BaseInterface__object;
struct sidl_BaseInterface__array;
typedef struct sidl_BaseInterface__object* sidl_BaseInterface;

Here is an example of the C client-side binding for an r-array. This example is for the solve example from Section 5.4. Here, I assume that the package name is num, and the class name is Linsol. The data for each array is passed as a double pointer, and the index parameters are normal in ints.


/** C client-side API for solve method */
void num_Linsol_solve(/* in */ num_Linsol self,
                      /* in rarray[m,n] */ double* A,
                      /* inout rarray[n] */ double* x,
                      /* in */ int32_t m,
                      /* in */ int32_t n,
                      /* out */ sidl_BaseInterface *_ex);

The one catch for C programmers is that A is in column-major order -- not the typical row-major ordering used in C. To access the element in row i and column j, you can use the RarrayElem2(A,i,j,m). RarrayElem2 is a convenience macro for C and C++ programmers to access r-arrays in column-major order, and it is defined in sidlArray.h. To access memory by stride one make i, the first index argument to RarrayElem2, your inner loop.

The additional argument _ex is used to indicate the presence of an exception when one has occured. In this case, the exception is possible because all methods implicitly throw sidl.RuntimeException . A non-NULL outcoming value in *_ex indicates that an exception occured. Exception handling is covered in Section 6.6.

Passing NULL for A, x, or b is not allowed. You must always pass a valid pointer.



babel-0.99.0
users_guide Last Modified 2006-04-20

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