Chapter 11  Fortran 90/95 Bindings

• Introduction
• Basics
• Client-side
• Implementation-side

11.1  Introduction

This chapter provides an overview of the Fortran 90/95 bindings for SIDL. Common aspects of the bindings, such as the mapping of SIDL data types to their native Fortran 90/95 representatives, are presented in Section 11.2. Issues of concern to Fortran 90/95 callers are addressed in the client-side bindings discussion in Section 11.3, while issues of interest to callees of Fortran 90/95 appear in the implementation-side discussion in Section 11.4.

11.2  Basics

This section summarizes basic features that are common to both client and implementation bindings. Conventions used to protect the global name space are described in Subsection 11.2.1, while those associated with the generation of subroutines from methods are given in Subsection 11.2.2. Translations between SIDL and native Fortran 90/95 constructs are described in Subsection 11.2.3. Finally, the process of casting between different types is illustrated in Subsection 11.2.4.

11.2.1  Name space

The name of the module that holds method definitions is derived from the fully qualified name of the class or interface. Module names are essentially formed by replacing all periods in the fully qualified name with underscores. The name of the module holding the derived type of the class or interface is the same as the one holding the methods with the exception of having _type appended. For example, the methods for sidl.SIDLException are defined in a module named sidl_SIDLException in the file sidl_SIDLException.F90. Defined in the file sidl_SIDLException_type.F90, the types for sidl.SIDLException are called sidl_SIDLException_t and, for the array, sidl_SIDLException_a.

11.2.2  Method signatures

All SIDL methods are implemented as Fortran 90/95 subroutines regardless of whether they have a return value. The name of a subroutine that clients invoke is the method’s full name from the SIDL description. Hence, in cases where the method has a name extension (so is overloaded), the full name is the concatenation of the specified short name and extension. On the implementation-side, the name is formed as the concatenation of the package, class (or interface), full method name, and “mi”, with each part separated by an underscore and name mangling used to ensure uniqueness if the resulting name exceeds the character limit.

The same process used for fortran 77, described in Subsection 10.2.2, is used to build up the parameters for generated methods. That is, object (or interface) pointers, return values, and exception pointers are added, as needed. More specifically, the object (or interface) pointer is automatically inserted as the first parameter in the signature of non-static methods. This parameter operates like an in parameter. When a method has a return value, a parameter to hold the return value is also added after all of the formally declared arguments. This extra argument behaves like an out parameter. With the addition of remote method invocation (RMI) support, all methods now implicitly throw exceptions. Hence, an extra out parameter for the exception is automatically added as the last parameter of the signature. An example that illustrates the SIDL specification and corresponding routines can be found in Subsections 11.3.5 and 11.4.4.

11.2.3  Data types

---

Table 11.1: SIDL to Fortran 90/95 Type Mappings

SIDL TYPE	Fortran 90/95 TYPE
int	INTEGER (kind=sidl_int)
long	INTEGER (kind=sidl_long)
float	REAL (kind=sidl_float)
double	REAL (kind=sidl_double)
bool	LOGICAL
char	CHARACTER (LEN=1)
string	CHARACTER (LEN=*)
fcomplex	COMPLEX (kind=sidl_fcomplex)
dcomplex	COMPLEX (kind=sidl_dcomplex)
enum	INTEGER (kind=sidl_enum)
opaque	INTEGER (kind=sidl_opaque)
interface	derived type
class	derived type
array	derived type

---

The mapping for simple SIDL types to Fortran 90/95 is given in Table 11.1. The kind parameters, given in the sidl F90 module, define integer parameters for sidl_int, sidl_long, sidl_float, sidl_double, sidl_fcomplex, sidl_dcomplex, sidl_enum and sidl_opaque to give sizes that match the corresponding SIDL types. The remainder of this subsection elaborates on mappings of strings, pointers, enumerations, and arrays.

Strings

The SIDL string type mapping is currently identical to that of the fortran 77 mapping. That is, all Fortran 90/95 strings have a limited fixed size. When implementing a subroutine with an out parameter, the size of the string is restricted to 512 characters.

NOTE: Modification of the value of SIDL_F90_STR_MINSIZE in runtime/sidl/babel_config.h prior to configuring Babel can be used to change the string size limitation.

Pointers

Pointer types are: opaque, interface, class, and array. This subsection elaborates on each within the context of the Fortran 90/95 language bindings. Opaque pointers are mapped to the equivalent of SIDL double. That is, the intermediate object reference (IOR) assumes a 64-bit integer is used to enable portability between systems with 32-bit and 64-bit address spaces. On a 32-bit system, the upper 32 bits of these quantities are ignored. Systems with more than 64-bit pointers aren’t currently supported. A derived type is used to hold opaque pointers for interfaces, classes, and arrays. The derived type for arrays of numeric types also has a pointer to an array to provide native access without function calls. For each interface and class, there are two modules created. In the first module, the derived type for the object and array are defined. In the second, methods for the object (or interface) and arrays of the object (or interface) are defined. Clients of a class (or interface), typically use the module containing the methods. It, in turn, uses the module containing the types.

Generally, clients should treat opaque, interface, class, and array values as black boxes. However, the value zero is special since it is the equivalent of NULL. Hence, any non-zero value is or should be a valid object reference. The method module provides built-in functions to test whether an interface, class, or array value is_null or is not_null. There is also a subroutine to initialize the value to set_null. Clients should generally initialize new class (or interface) pointers to NULL.

Enumerations

SIDL enumerations map to integer values, which are defined in a module. Given the specification from Section 6.3 for an enumeration type called car, Babel will produce the following enumerated type:

Arrays

As discussed in Section 6.4, SIDL supports both normal and raw arrays (i. e., r-arrays). Normal SIDL arrays can be used by any supported language; whereas, r-arrays are restricted to numeric types and use in languages such as C, C++, and Fortran. This subsection starts with a discussion normal and generic arrays before proceeding with an example of the interfaces for r-arrays.

The normal SIDL array API is available in a module for creating, destroying, and accessing array elements and meta-data for normal arrays. More information on the API can be found in Subsection 6.4. For sidl.SIDLException, the array module — called sidl_SIDLException_array — is defined in sidl_SIDLException_array.F90. The derived type for a SIDL array is named after the class, interface, or basic type that it holds and the dimension of the array. For sidl.SIDLException, the array derived types are named sidl_SIDLException_1d, sidl_SIDLException_2d, sidl_SIDLException_3d, … up to sidl_SIDLException_7d. For basic types, they are treated as sidl.dcomplex, sidl.double, sidl.fcomplex, etc. Each of these derived types has a 64-bit integer to hold an opaque pointer.

NOTE: Normal Fortran 90/95 arrays or normal SIDL arrays can be used when calling a Fortran 90/95 method, but they cannot be mixed.

Derived types for SIDL types dcomplex, double, fcomplex, float, int, and long have pointers to arrays of the appropriate type and dimension that facilitate direct access to array elements. For example, the derived type for 2d and 3d arrays of doubles is:

For the other types, the array API must be used to access elements. In this case, the array can be accessed with the F90 array pointer d_data just like any other F90 array. However, the F90 built-in methods allocate or deallocate on d_data must not be used. Instead, SIDL functions, createCol, createRow, create1d, create2dRow, or create2dCol, must be used to create a new array. These SIDL routines initialize d_data to refer to the data allocated in d_array.

NOTE: create1d, create2dRow, and create2dCol create arrays whose lower index is 0 not 1. To create arrays with a lower index of 1, createCol or createRow must be used.

Software packages like LINPACK or BLAS can be called, but the stride should be checked to make sure the array is suitably packed. Using stride(i) will provide the distance between elements in dimension i. A value of 1 means elements are packed densely. Negative stride values are possible and, when an array is sliced, the resulting array might not even have one densely packed dimension.

As discussed in Section 6.4, the type of a generic array is not specified. As a result, Fortran 90/95 represents generic arrays as the derived type sidl__array as defined in the sidl_array_type module. (Note the use of a two underscore separator.) The following subroutines, defined in the sidl_array_array module, apply to generic arrays: addRef, deleteRef, dimen, type, isColumnOrder, isRowOrder, is_null, no_null, set_null, lower, upper, length, stride, and smartCopy.

Finally, SIDL r-arrays are passed to and from methods as normal Fortran 90/95 arrays. Index variables do not need to be included because the values are determined from the Fortran 90/95 array extents in each dimension. For example, the client-side interface for solve — introduced in Section 6.4 — behaves as if it is a Fortran 90/95 function with the following overloaded interface:

The server-side interface, shown below, is similar.

NOTE: The lower index of each dimension of every incoming array is always zero.

11.2.4  Type casting

Babel automatically generates the cast() method for casting between different interface and class types. Actually, a set of overloaded methods support every allowable cast between a type and all its parent types (both objects and interfaces). The first argument is the object (or interface) to be cast, and the second is a variable of the desired type. The cast is successful if, after the call to cast(), the value of the second argument is not_null. The caller then owns (and is responsible for) the returned reference. Examples of type casting can be found in Subsections 11.3.5 and 11.4.4.

11.3  Client-side

This section summarizes aspects of generating and using the Fortran 90/95 bindings associated with software wrapped with Babel’s language interoperability middleware. The bindings generation process is presented first. Object management and invocation of static and overloaded methods are also summarized. The process of catching exceptions is then discussed. Finally, the processes for enabling and disabling implementation-specific pre- and post-method instrumentation — referred to as “hooks” — are illustrated.

11.3.1  Bindings generation

The following is an example of invoking Babel to create the Fortran 90/95 stubs for a SIDL file¹:

% babel --exclude-external --client=f90 file.sidl

or simply

% babel -E -c=f90 file.sidl

As a result, a makefile fragment called babel.make, numerous C header and source files, and some Fortran 90/95 files will be created. Files ending in _fStub.c (i. e., STUBSRCS in babel.make) are called by the Fortran 90/95 module which in turn allow Fortran 90/95 to call SIDL methods. Files ending in _type.F90 (i. e., STUBMODULESRCS in babel.make) contain derived type definitions for classes and interfaces. The remaining files ending in .F90 (i. e., TYPEMODULESRCS in babel.make) are Fortran 90/95 modules containing methods. All of these files need to be compiled and linked into the application.

Normally, IOR files (i. e., those ending in _IOR.c) are linked together with the implementation file, so probably don’t need to be compiled.

11.3.2  Object management

SIDL-specified objects are managed through explicit creation and reference counting. Babel automatically generates a new() method for concrete classes. The method is used to instantiate the class and return the associated reference. The following example illustrates the instantiation and casting of an object to an interface:

The owner of the instance is responsible for its proper disposal. In other words, when processing with the object is done, the owner must invoke deleteRef() on it. Similarly, any object references returned by a subroutine call must be deleted or given to another part of the code that will take ownership of and, therefore, responsibility for deleteRef’ing it. The following example illustrates calling deleteRef() using the sidl.BaseInterface method:

When it is necessary to determine if two references point to the same object, the built-in isSame method can be used. For example, the following attempts to determine if interface1 and interface2 point to the same object:

11.3.3  Static methods

Below is an example illustrating a call to addSearchPath(), which is a static method in the sidl.Loader class.

Note the function is invoked directly, without an object reference argument.

11.3.4  Overloaded methods

Examples of calls to SIDL overloaded methods are based on the overload_sample.sidl file shown in Section 6.7. Recall that the file describes three versions of the getValue method. The first takes no arguments, the second takes an integer argument, and the third takes a boolean. Each is called in the following code snippet:

11.3.5  Exception catching

Since all methods can now throw sidl.RuntimeException , Babel ensures there is an out argument to hold an exception. If not explicitly specified, Babel will automatically add the argument. For maximum backward compatibility, the exception argument type is sidl.BaseInterface, while the base exception class is sidl.SIDLException. The exception argument, which behaves like an out parameter, will appear after the return value when both occur in a method. After the call, the client should test this argument using is_null or not_null. If it is not_null_null, an exception was thrown by the method so the caller should respond appropriately. When an exception is thrown, the values of all other arguments are undefined. So the best course of action is to ignore them. If the code does not check the exception argument after each call (that can throw one), any exceptions that are thrown will be utterly ignored as a result of not being automatically propagated to higher level routines.

It is possible to determine which exception was thrown through casting the argument. A successful cast indicates the type of exception that occurred. An example of this process is illustrated below. Package ExceptionTest has a class named Fib with a getFib method declared in SIDL as follows:

The code to catch specified exception types is:

NOTE: Any caller of a method that returns an exception should ignore the values of out and inout parameters. Anything not freed becomes a reference and memory leak.

11.3.6  Hooks execution

If a given component supports pre- and post-method invocation instrumentation, also known as “hooks”, their execution can be enabled or disabled at runtime through the built-in set_hooks method. For example, given the following SIDL specification:

which has a single static function and a member function for the Basics class. Due to unresolved method overloading problems, the processes for enabling and disabling execution of the implementation-specific hooks are currently dependent on use of fully-qualified functions, as illustrated below.

It is important to keep in mind that the set_hooks_static method must be used to enable/disable invocation of hooks for static methods and the set_hooks method must be used for those of non-static methods. Also, Babel does not provide client access to the _pre and _post methods; therefore, they cannot be invoked directly. More information on the instrumentation process is provided in Subsection 11.4.5.

11.3.7  Contract enforcement

Interface contracts specify the expected behaviors of clients and servers of interface and class methods. Once specified, contracts can automatically be enforced at runtime. This section provides an example of a specification and associated code snippets for performing basic, traditional contract enforcement — introduced in Section 6.5 — within a Fortran 90/95 client.

A SIDL specification, including preconditions and postconditions, for calculating the sum of two vectors is given below. (Refer to Section 6.5 for an introduction to the contract syntax.) According to the preconditions, all callers are expected to provide two one-dimensional, SIDL arrays of the same size as arguments. The postconditions specify that all implementations are expected to return a non-null, one-dimensional array of the same size (as the first SIDL array), assuming the preconditions are satisfied.

An example of a Fortran 90/95 client calling the method is given below. The code snippet illustrates declaring and creating the arrays; enabling full contract enforcement (i. e., checking all contract clauses); executing vuSum; handling contract violation exceptions; and cleaning up references is given below.

Alternative enforcement options can be set, as described in Section 6.5, through the two basic helper methods: setEnforceAll and setEnforceNone. The code snippet below shows the Fortran 90/95 calls associated with the traditional options of enabling only precondition enforcement, enabling postcondition enforcement, or completely disabling contract enforcement.

This section illustrates the basic interfaces and processes for traditional interface contract enforcement for a Fortran 90/95 client. Additional enforcement policy options and methods as well as more information regarding the specification and enforcement of contracts can be found in Chapter 21.

11.4  Implementation-side

This section summarizes aspects of generating and wrapping software written in Fortran 90/95. The bindings generation and basic implementation processes are presented first. Since access to object state requires special steps in Fortran 90/95, the process for defining and managing that data is discussed. Throwing exceptions in the implementation is then illustrated. Finally, the results of generating implementations with pre- and post-method “hooks” are shown.

11.4.1  Bindings generation

Much of the information associated with generating client-side bindings is pertinent to implementing a SIDL class in Fortran 90/95. The mapping of SIDL types to language constructs was given in Table 11.1. If the implementation calls other SIDL methods, client-side caller rules must be followed.

To create the implementation bindings for a set of SIDL classes in Fortran 90/95, Babel is invoked as follows:

% babel --exclude-external --server=f90 file.sidl

or simply

% babel -E -s=f90 file.sidl

As a result, a makefile fragment called babel.make, numerous C header and source files, and some Fortran 90/95 source files will be created. The SUBROUTINE and END SUBROUTINE statements are automatically generated and the types of arguments declared. Implementation details must be added to the Fortran 90/95 “Impl” files, whose names end with _Impl.F90 and _Mod.F90. More on this matter is provided in Subsection 11.4.2.

11.4.2  Bindings implementation

Implementation details must be added to the “Impl” files generated in Subsection 11.4.1. Changes to these files must be made between code splicer pairs to ensure their retention in subsequent invocations of Babel. Below is an example of the standard, automatically generated code splicer pairs.

The comment “Insert-Code-Here” associated with the “miscellaneous code start” splicer pair will need to be replaced with details such as additional abbreviation file(s) and any local, or private, subroutines. For the subroutine’s “use” splicer pair, the “Insert-Code-Here {Pkg.Class.name.use} (use statements)” comment must be replaced with any use statements needed by the subroutine. Finally, the implementation between the subroutine body’s splicer pairs must be added in place of the “Insert-Code-Here {Pkg.Class.name} (name method)” comment.

11.4.3  Private data

Any variables declared in the implementation source file will, by virtue of Babel’s encapsulation, be private. Special initialization procedures can be added to the built-in _load() method, which is guaranteed to be called exactly once per class to set global class data — before any user-defined methods can even be invoked.

The SIDL IOR keeps a pointer for each object that is intended to hold a pointer to the object’s internal data. Below is an excerpt from a _Mod.F90 file for an object whose state requires a single integer value.

The derived type sort_SimpleCounter_priv is the type in which the developer adds data to store the object’s state. The sort_SimpleCounter_wrap type exists simply to facilitate transferring the sort_SimpleCounter_priv pointer to and from the IOR.

Access to this data is provided by two built-in functions — referred to as set_data and get_data — whose full names are derived from the fully qualified type name. In both cases, the first argument is the object pointer (i. e., self), and the second is a derived type defined in the _Mod.F90 file. The developer is responsible for managing the memory associated with the private data.

As illustrated in the constructor below, the basic process to initialize private data involves allocating memory then setting the data pointer.

Note the use of allocate(pd%d_private_data) in the constructor, _ctor, to allocate the memory for the sort_SimpleCounter_priv derived type and the fully qualified name for get_data.

Similarly, the destructor is responsible for freeing the data’s memory as follows:

In this case, deallocate(pd%d_private_data) is used to free the memory allocated in the constructor for the sort_SimpleCounter_priv derived type.

11.4.4  Exception throwing

Below is an example of an implementation subroutine that throws an exception. The returned exception object pointer must be cast into the exception out parameter. This example also utilizes two methods, inherited from sidl.BaseException and implemented in sidl.SIDLException, that aid client-side debugging. The first, setNote, allows the developer to provide a useful error message. The second, add, provides a multi-language traceback capability — assuming each layer of the call stack invokes add before it propagates the exception.

When an exception is thrown, the implementation should deleteRef any references it was planning to return to its caller. In general, when throwing an exception, it is good practice to call set_null on all out and inout array, class, and interface arguments before returning. This makes things work out better for clients who forget to check if an exception occurred or willfully choose to ignore it.

11.4.5  Hooks implementation

As discussed in Subsection 11.3.6, when hooks execution is enabled, implementation-specific instrumentation is executed. Using the --generate-hooks option on the Babel command line when generating implementation-side bindings results in the automatic generation of a _pre and _post method for every static and non-static method associated with each class in the specification. For the aStaticMethod specified in Subsection 11.3.6, the generated _pre method implementation is:

while that of the _post method is:

Per the normal implementation process, the desired instrumentation should be added within the splicer blocks of aStaticMethod_pre and aStaticMethod_post. As stated in the comments within those blocks, aStaticMethod_pre will be executed immediately prior to dispatch to aStaticMethod when the latter is invoked by a client. Assuming no exceptions are encountered, aStaticMethod_post is executed immediately upon return from aStaticMethod.

1

For information on additional command line options, refer to Section 4.2.