Disclaimer

This work was performed under the auspices of the U. S. Department of Energy by Lawrence Livermore National Laboratory in part under Contract W-7405-Eng-48 and in part under Contract DE-AC52-07NA27344.
This document was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the University of California nor any of their employees, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or the University of California. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or the University of California, and shall not be used for advertising or product endorsement purposes.

Chapter 1  Preface

Babel in a Nutshell

Babel is a tool that enables software written in different languages to communicate. It accomplishes this task by using an Interface Definition Language (IDL) similar to COM and CORBA. Babel relies on the Scientific Interface Definition Language (SIDL) that is specifically tuned for scientific applications. By expressing software interfaces, or APIs¹, in SIDL the appropriate glue code stubs and skeletons can be generated to facilitate language interoperability. Features unique to SIDL are:

• Dynamic multi-dimensional arrays
• Complex numbers (e. g. 2 + 3i)
• In-process optimizations
• Syntax for specifying executable interface contracts
• Special directives for large-scale parallel distributed programming (future)

Babel enables true object-oriented techniques even in non object-oriented languages. The object model that SIDL supports is similar to Java and Objective C where a class can extend at most one class, but implement many interfaces. In C++ speak, an interface is simply a class of all pure-virtual methods. Furthermore, if library developers want object-oriented features but are required to be 100% ANSI C compliant, Babel can meet those constraints. Although the Babel code generator is implemented in Java, the runtime libraries and generated files for C bindings are 100% ANSI C compliant.

Babel can be used as the basis for a component framework, but it is not a complete framework by itself. We’ve added a tiny CCA-compliant framework, called Decaf, in our examples/ directory. Decaf demonstrates how Babel can be used to implement a component framework.

SIDL is also a useful communications tool for code development teams since it only expresses the public API. That is, implementation details, which often prove distracting during collaborative design, can be safely avoided by restricting discussions to the interfaces described in SIDL. Furthermore, since SIDL is simple and clean it can be used by Computer Scientists, Math Programmers, and Application Scientists to debate APIs even using only email.

Scope of this Manual

This document is intended as an introduction and tutorial on the use of Babel tools for the generation and use of component software. The Babel tools were designed specifically for scientific applications, therefore most of the examples and exercises here also deal with scientific applications.

This manual assumes the reader is a programmer who is proficient in two or more of the following languages: C, C++, fortran 77, Fortran 90/95, Fortran 2003/2003, Java, or Python. Furthermore, this manual assumes the reader is familiar with the SPMD² programming model that pervades the scientific computing community. Knowledge of and experience with MPI programming is helpful, but not strictly required.

Getting the Software

Babel source is available free of charge on the web. Developed by the Components Project at the Lawrence Livermore National Laboratory Center for Applied Scientific Computing (CASC), it is licensed under the Lesser GNU Public License (LGPL). See the source distribution for details.

The homepage for the Components Project is

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

Conventions

The following typographic conventions are used throughout this manual.

Additionally, we may use specific blocks of text as sidebars to call the readers attention to particular information. Here’s one kind.

Rationale: Often when listing restrictions or requirements, we find it helpful to also explain and document the rationale behind a design decision. In time, the context in which the rationale was based may become irrelevant, making the rationale blocks very useful for understanding when to change a decision.

We Appreciate Your Feedback

We have tested and verified the information in this manual. Nonetheless, features may have changed or oversights may exist. Please contact us with any issues, corrections, or suggestions for future versions of this manual through snail mail at:

Components Project
Center for Applied Scientific Computing
Lawrence Livermore National Laboratory
P. O. Box 808, L–561
Livermore, CA 94551

or through email to:

components@llnl.gov

To find out more about Babel, feel free to subscribe to one or more of the associated distribution lists given below.

• babel-announce@llnl.gov is a moderated email forum to which anyone can subscribe (though no-one can post). This is a low-volume alternative for people who want to know about releases and major announcements.
• babel-dev@llnl.gov is an open discussion forum about Babel for serious babel users who want to talk about the internal workings of the tools. Anyone can subscribe or send email to this list.
• babel-users@llnl.gov is an open discussion forum about Babel for users. Anyone can subscribe or send email to this list.

To subscribe, simply send email to majordomo@lists.llnl.gov with the appropriate line(s):

subscribe babel-announce [email-address]
subscribe babel-dev [email-address]
subscribe babel-users [email-address]

where you can explicitly state your email address in email-address or, if you leave email-address blank, majordomo will use your email ReplyTo: field.

Acknowledgments

Active Team Members:

Tom Epperly (Project Lead), Tamara Dahlgren, and Adrian Prantl.

Project Alumni:

Bill Bosl, Kevin Durrenberger, Nathan Dykman, Dietmar Ebner, Scott Kohn, Gary Kumfert, James Leek, Steve Smith, and Brent Smolinsky.

Interns:

Irina Abramova, USC (Summer 2009), Jewel Watts, NCAT (Summer 2009), Monica Porsche, Central State University (Summer 2008), Nija Shi, UC Davis (Summer/Fall 2004), Kirk Kelsey, (Summer 2004), Sarah Knoop, UW Madison (Summer 2003), and Melvina Blackgoat, NAU (Summer 2001).

Alpha Testers:

Andy Cleary, Jeff Painter, and Cal Ribbens

Contributors (Ideas, Bug Reports, Patches, & Code):

Rob Armstrong, Ben Allan, Wael Elwasif, Matt Knepley, Boyana Norris, Barry Smith, Jody Winston, and many more.

Sponsors:

Babel development originally started as a Strategic Initiative (SI) in the LDRD (Lab Directed R&D) portfolio of Lawrence Livermore National Laboratory. Follow-on funding comes through collaborations with the Common Component Architecture (CCA) Forum (http://www.cca-forum.org/wiki). Specifically, the U.S. Department of Energy (http://www.doe.gov/) supports the project through the Office of Science (http://sc.doe.gov/) SciDAC program (http://www.scidac.gov/). Initial follow-on SciDAC funding came as part of the Center for Common Component Technology for Terascale Scientific Simulation (CCTTSS). Current SciDAC II funding is part of the Center for Technology for Advanced Scientific Component Software (TASCS) (http://tascs-scidac.org/).

Software Notices

Babel depends on a great deal of third-party software.

• JavaCC is used to generate the SIDL Parser. This is a java.net community project. JavaCC is available under a BSD-style license here: https://javacc.dev.java.net/).
• gnu.getopt is an implementation of GNU Getopt in Java and is distributed with Babel as a JAR file. It can be downloaded (along with sourcecode) from either the GNU website

  http://www.gnu.org/software/java/packages.html
   

  or the author’s website

  http://www.urbanophile.com/arenn/hacking/download.html.
   

  The following is the copyright notice for gnu.getopt:

  /**************************************************************************
  /* Getopt.java -- Java port of GNU getopt from glibc 2.0.6
  /*
  /* Copyright (c) 1987-1997 Free Software Foundation, Inc.
  /* Java Port Copyright (c) 1998 by Aaron M. Renn (arenn@urbanophile.com)
  /*
  /* This program is free software; you can redistribute it and/or modify
  /* it under the terms of the GNU Library General Public License as published 
  /* by  the Free Software Foundation; either version 2 of the License or
  /* (at your option) any later version.
  /*
  /* This program is distributed in the hope that it will be useful, but
  /* WITHOUT ANY WARRANTY; without even the implied warranty of
  /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  /* GNU Library General Public License for more details.
  /*
  /* You should have received a copy of the GNU Library General Public License
  /* along with this program; see the file COPYING.LIB.  If not, write to 
  /* the Free Software Foundation Inc., 59 Temple Place - Suite 330, 
  /* Boston, MA  02111-1307 USA
  /**************************************************************************/
   

  The text for the GNU Library GPL is available at http://www.gnu.org/copyleft/library.html.

1

Application Programming Interfaces

2

Single Program Multiple Data

Contents

• Chapter 1  Preface
• Chapter 2  Introduction
  • 2.1  Babel Facilitates Language Interoperability
  • 2.2  Scientific Interface Definition Language (SIDL)
  • 2.3  Benefits to Customers
  • 2.4  Beyond Babel’s Scope
  • 2.5  Summary
  • 2.6  Organization

• Part I  Foundations
  • Chapter 3  Installation
    • 3.1  Simple Installation
    • 3.2  External Software Requirements
  • Chapter 4  Basic Babel Code Generation
    • 4.1  Babel is a Compiler
    • 4.2  Command Line Options
  • Chapter 5  Hello World Tutorial
    • 5.1  Introduction
    • 5.2  Minimal Makefiles
    • 5.3  Portable Makefiles: using babel-config
    • 5.4  Final Remarks
  • Chapter 6  SIDL Basics
    • 6.1  Introduction
    • 6.2  SIDL Files
    • 6.3  Fundamental Types
    • 6.4  Arrays
    • 6.5  Interface Contracts
    • 6.6  SIDL Runtime
    • 6.7  Objects
    • 6.8  XML Repositories
  • Chapter 7  Upgrade Notes
    • 7.1  Upgrading from Babel 1.0 to 1.4
• Part II  Supported Language Bindings
  • Chapter 8  C Bindings
    • 8.1  Introduction
    • 8.2  Basics
    • 8.3  Client-side
    • 8.4  Implementation-side
  • Chapter 9  C++ Bindings
    • 9.1  Introduction
    • 9.2  Basics
    • 9.3  Client-side
    • 9.4  Implementation-side
  • Chapter 10  FORTRAN 77 Bindings
    • 10.1  Introduction
    • 10.2  Basics
    • 10.3  Client-side
    • 10.4  Implementation-side
  • Chapter 11  Fortran 90/95 Bindings
    • 11.1  Introduction
    • 11.2  Basics
    • 11.3  Client-side
    • 11.4  Implementation-side
  • Chapter 12  Fortran 2003/2008 Bindings
    • 12.1  Introduction
    • 12.2  Basics
    • 12.3  Client-side
    • 12.4  Implementation-side
  • Chapter 13  Java Bindings
    • 13.1  Introduction
    • 13.2  Basics
    • 13.3  Client-side
    • 13.4  Implementation-side
  • Chapter 14  Python Bindings
    • 14.1  Introduction
    • 14.2  Basics
    • 14.3  Client-side
    • 14.4  Implementation-side
  • Chapter 15  SIDL Backend
    • 15.1  Introduction
    • 15.2  Purpose
    • 15.3  Generated versus Original SIDL files
    • 15.4  XML File Comparison
    • 15.5  Babel Command Line Options
  • Chapter 16  XML Backend
    • 16.1  Introduction
    • 16.2  Purpose
    • 16.3  Basic Structure
    • 16.4  Command Line Options
  • Chapter 17  HTML Interface Documentation
    • 17.1  Introduction
• Part III  Advanced Topics
  • Chapter 18  Remote Method Invocation
    • 18.1  What is RMI?
    • 18.2  Babel RMI Concepts
    • 18.3  Babel RMI Usage
    • 18.4  Babel Object Servers
    • 18.5  Non-Blocking Babel RMI
  • Chapter 19  Building Portable Polyglot Software
    • 19.1  Layout of Generated Files
    • 19.2  Grouping compiled assets into Libraries
    • 19.3  Dynamic vs. Static Linking
    • 19.4  SIDL Library Issues
    • 19.5  Language Bindings for the sidl Package
    • 19.6  SCL Files for Dynamic Loading
    • 19.7  Deployment of Babel-Enabled Libraries
  • Chapter 20  Creating Objects with Pre-Initialized State
    • 20.1  Introduction to the Backdoor Initializer
    • 20.2  Motivation
    • 20.3  Example
    • 20.4  The Backdoor Initializer in C
    • 20.5  The Backdoor Initializer in fortran 77
    • 20.6  The Backdoor Initializer in Fortran 90/95
    • 20.7  The Backdoor Initializer in C++
    • 20.8  The Backdoor Initializer in Java
    • 20.9  The Backdoor Initializer in Python
  • Chapter 21  Interface Contracts
    • 21.1  Introduction
    • 21.2  Specifications
    • 21.3  Enforcement
    • 21.4  Summary
  • Chapter 22  Troubleshooting
    • 22.1  Introduction
    • 22.2  Common Errors
    • 22.3  Common Warnings
  • Chapter 23  Lessons Learned
    • 23.1  Introduction
    • 23.2  Compilation Consistency is Key
• Part IV  Appendices
  • Appendix A  Reserved Words
    • A.1  Introduction
    • A.2  Reserved Words
    • A.3  Suggested Things To Avoid
  • Appendix B  SIDL Grammar
    • B.1  Introduction
    • B.2  Backus-Naur Form
  • Appendix C  Extensible Markup Language (XML)
    • C.1  Introduction
    • C.2  SIDL Document Type Declaration (DTD)
  • Appendix D  Glossary
  • ibliography

Chapter 2  Introduction

2.1  Babel Facilitates Language Interoperability

Babel was conceived, designed, and built to solve a problem; namely, to make scientific software libraries equally accessible from all of the standard languages. Hence, its goal is language interoperability. The vision goes far beyond calling BLAS¹ implemented in fortran 77 from a C program. At its heart, Babel lets programmers use their tool of choice in developing complete applications using components implemented in one or more distinct programming languages.

---

Figure 2.1: Example Babel multi-language application

---

For instance, let us say that an application scientist is running a sophisticated C++ code from a Python scripting environment. This can already be easily accomplished with technologies like SWIG. Now let’s say that the simulation is showing some erratic behavior and the application scientist wants to extend the ConvergenceCheck class to also report some information to a log file. Let’s also assume that this application scientist doesn’t want to write a new C++ class much less rewrite the current application. What this individual wants to do is derive and utilize a new class in Python from the C++ ConvergenceCheck class. Thus, the C++ simulation code will now have to invoke a method on a class implemented in Python, which then dispatches back to the C++ base class after doing its additional logging. In Babel, this situation is normal and expected. In SWIG, one must use special settings to enable the director feature to have this level of flexibility, which increases the code size and complexity. Figure 2.1 shows a high level view of what Babel’s solution looks like. The developers write the application in Python, the library in C++, and the extended ConvergenceCheck in Python. All the glue code is generated by running Babel on a SIDL file.

---

Figure 2.2: Language Interoperability Using Current Technology.

---

Figure 2.2 lists many of the primary languages that are of interest to scientific simulation software developers and users. The good news is that there is a path from each language to every other; meaning that calling from one to another is possible. However, the technologies to get from one language to another vary widely, are fraught with pitfalls, and may require calling through a completely different language.

Babel works by providing the technology to define and support the multi-language interoperation of a common subset of functionality through programming language-neutral interface specifications. See Fig. 2.3 to see a graphical representation of the supported languages. It is important to note that this common functionality subset is far from a lowest common denominator solution in that Babel actually adds functionality when it is lacking in the host language.

---

Figure 2.3: Language Interoperability Using Babel.

---

2.2  Scientific Interface Definition Language (SIDL)

In order to support multi-language interoperability, Babel relies on the specification of interfaces in the Scientific Interface Definition Language (SIDL) (pronounced “SIGH-dull”). SIDL is similar to COM and CORBA IDLs, but was designed with an emphasis on scientific computing. Specifically, SIDL supports dynamic multi-dimensional arrays and has built-in complex numbers. SIDL also supports interface contracts, which define properties that must hold true during execution — before and/or after method invocation — when contract enforcement is enabled. It will acquire a set of directives to aid in the description of massively parallel distributed objects.

When it comes to deciding what programming idioms to support across all languages and which ones to reject, SIDL strikes a careful balance between minimalism and completeness. It is not a lowest common denominator solution. SIDL is minimal to keep the learning curve as low as possible. It is complete so developers do not feel constrained in how to express their solutions.

SIDL is object-oriented. Its object model closely resembles that of Java and Objective C. In this model there is single inheritance of implementation and multiple inheritance of interfaces. It supports the typical notions of virtual, static, and final methods. SIDL also provides a basic set of features by defining and implementing the basic types for interfaces, classes and exceptions. All types implicitly inherit from these basic types.

The most important concept to grasp about SIDL is that SIDL only defines a public interface that other programs may use to access your code. As a result, all methods defined as part of a SIDL file are public; if you do not want a method to be globally usable, simply do not define it in your SIDL file. Furthermore, all object and class data is implicitly private. There is no way to declare or define data in a SIDL file. Instead, any data required for your code should be declared in the implementation language files. This way, the languages that use your code through Babel may create your objects and pass them around just like any normal piece of data, but they may only access the data through the provided interface.

SIDL also has a complete set of fundamental data types, from booleans to double precision complex numbers. It also supports more sophisticated types such as enumerations, strings, objects, and dynamic multi-dimensional arrays.

SIDL is still a work in progress. Of particular research interest are directives that will be added for parallel distributed object interaction and features to specify computational quality of service semantics associated with the interfaces.

2.3  Benefits to Customers

Babel has two types of customers: developer and user. The developer implements a library that will be used by one or more users, and the user uses libraries via their Babel generated interfaces. Babel provides value to developers by making their software accessible to a larger customer base because their software can be used from more different programming languages. Users, on the other hand, may not care or even know that they are interacting with a library through Babel. Babel provides value to users by making more software accessible to them.

Babel provides some features that benefits user and developer alike. The most important aspect to note here is that all Babel objects are reference counted. This feature is critical to encapsulate the memory allocation library (e. g. C’s malloc/free or C++’s new/delete) used in the implementation of the object. Users never need concern themselves with when to free up a resource, they only declare when they’re done with their reference to that resource. Developers are free to use different memory allocation subsystems in different parts of their code if need be.

Babel also provides a consistent type system. This is particularly important when you want to make object-oriented libraries written in C++, Python or Java accessible in procedural languages like fortran 77, Fortran 90/95 and C. Babel maps the object-oriented concepts like inheritance, polymorphism and object identity into all supported languages.

Interface contracts , which identify conditions that must hold at the interface boundary, can be used to improve the quality of software for both developers and users. Interface contracts consist of precondition, postcondition, and/or invariant clauses belonging to the interface, not the underlying implementation(s). Precondition clauses consist of assertions on properties which must hold prior to method execution. Postcondition clauses contain assertions which must hold upon method completion. Invariant clauses apply before and after method execution. Consequently, in addition to providing useful documentation, SIDL interface contracts are enforceable. So developers can enable contract enforcement as an aid to testing and debugging. Users can enable full or partial contract enforcement during deployment to gain confidence in unfamiliar software.

2.4  Beyond Babel’s Scope

The language interoperability problem is a large one, and though the Babel tools address much of it, there is still a lot that is beyond the scope of our tool. Babel is at its heart a code generator and a runtime library. Consequently, the following features are currently limitations of the Babel tool kit:

Reverse engineering

is not supported. That is, there is no support for inspecting or modifying compiled code. In addition, scanning existing software to generate SIDL wrappers is not supported. There are other groups who are pursuing a C++ to SIDL converter. Since SIDL contains different information than what is in a C++ header file, however, such a converter cannot be fully automated without additional help.

Library compatibility

is limited. Since Python and Java dynamically load libraries into their virtual machines, using these languages requires the ability to build shared libraries. In general, building shared libraries (particularly from C++) is difficult and error prone. This is compounded by the fact that compiler vendors have no standard way of doing this, and many tools that help building shared libraries don’t support C++. One can build a legitimate shared library that still won’t work because there are unresolved symbols, or the library was loaded in the wrong mode.

Compiler compatibility

is limited. Since the C++ standard does not specify a binary interface and uses a lot of hashing in their symbol tables, there have been no attempts to get libraries from dissimilar C++ compilers to work together. Similarly, although we support fortran 77 and Fortran 90/95, all libraries of Fortran code must be compiled with the same compiler…again because of the lack of a standard binary interface.

Despite the aforementioned limitations, Babel does facilitate the development of language interoperable software. However, issues of robust packaging, building, and deployment of language interoperable software still loom on the horizon.

2.5  Summary

Babel consists of a set of tools intended to facilitate language interoperability in the scientific computing community. Using interfaces for libraries or components specified in Scientific Interface Definition Language (SIDL) files, Babel can generate corresponding XML representations as well as the source code for the corresponding stubs, intermediate object representations, and implementation skeletons. The generated source code then becomes the foundation for the glue code used for language interoperability between callers of libraries and components.

In addition to providing generated code automatically handling mapping fundamental data type parameters between different languages, Babel has built-in support for complex numbers and multi-dimensional arrays. Additional benefits include object reference counting to facilitate memory management.

Optional SIDL interface contract features are also provided. Interface contracts aid in improving the quality of software. Contracts added to interfaces document constraints and can be used to enhance testing. When enabled at runtime, contracts can also be used to help users gain confidence in unfamiliar software.

Finally, Babel’s primary goal is to facilitate the development of language interoperable libraries and components. Hence, support for reverse engineering is not provided. Given that Babel has been developed by a research team, there are also limitations associated with shared library and programming language-specific compiler interoperability support that have been looked into but probably will not be addressed in the foreseeable future. Regardless, Babel has proved to be useful to its stakeholders to the point that it is becoming an integral part of the Common Component Architecture (CCA). Refer to papers and presentations on our web site for more information.

2.6  Organization

The remainder of this document is separated into two parts: foundations and supported language bindings. Part I is devoted to describing the SIDL and the Babel tools. It starts with a tutorial to gently introduce the reader to the development of glue code from both the implementation (or server) and user (or client) sides. The following chapter introduces SIDL and Babel basics. Finally, a chapter on advanced topics, such as linking options, is provided.

Part II describes the language bindings currently supported by Babel. Most of the bindings are programming languages. In which case, most have both client- and server-side bindings. However, Babel also supports textual language backends. At this time, Extensible Markup Language (XML), Hypertext Markup Language (HTML) and Scientific Interface Definition Language (SIDL) are the only textual backends.

Appendices are included to provide more information on topics such as acronyms, the SIDL Grammar, and SIDL XML. In addition, sections are included that provide advice and tips on troubleshooting.

1

BLAS: Basic Linear Algebra Subroutines

Chapter 3  Installation

Ideally, Babel will configure and make “out-of-the-box” on most Unix-like machines. If the configuration process detects that certain resources are unavailable, it will correctly disable support for languages or features needing those resources. If this instance of correct behavior is not the intended behavior, then the installer is left to install the external resources and then re-configure, make, and install Babel. This chapter is intended to provide help and reassurance that Babel is indeed configured and installed correctly.

3.1  Simple Installation

These instructions assume you have a “tarball” (e. g. *.tar.gz file). We have volunteers who put together and manage RedHat RPMs and Debian *.deb distributions of Babel. If you have one of these distros, read their documentation first as it may have details that supersede our own.

A typical build is a simple sequence of

% ./configure -C
# lots of stuff
...
Fortran77 enabled.
C++ enabled.
Java enabled.
Python enabled.
Fortran90 enabled.
% make
# lots more stuff
...
% make install
# not so much stuff
...

The -C tells configure to cache its results in a file. This improves the overall speed of configuration because the runtime configure script reuses the results of the top-level configure.

There are many circumstances where the configuration step will properly terminate with an error, but if the configuration works, the build and installation shouldn’t terminate abnormally. If you have problems or note bugs during configuration, installation or later Babel usage, please send an email to babel-bugs@cca-forum.org including the version of babel you are working with, if possible the output from babel-config --version-full, and the exact output that indicates the presence of a bug. babel-config is Bourne shell script that the configure creates in the bin directory. If your current directory is the top directory of the Babel distribution, normally you can invoke babel-config as follows:

% bin/babel-config --version-full

3.1.1  Configure

There are two main choices to be made at configure time: “Where does the software get built?” and “Where does the software get installed?”. The mechanisms for effecting these choices are quite different.

If you want to build software in a separate directory from where the tarball was untarred, this is called a “VPATH build”. VPATH builds are useful if you want to build Babel multiple times with various compilers, flags, or you have a shared filesystem across multiple platforms. It separates the code you generate from things that you were given. The downside is that it is more complex to remember where to edit what since original sources will be in the source directory tree and the generated sources and compiled assets will be in the build directory tree.

If you run configure in the directory it appears, (i. e. you typed ./configure) you are performing an “non-VPATH build”. To do a VPATH build, simply cd to the directory you want to be the build directory root, then launch configure from there. The following sequence demonstrates a vpath build

% tar zxvf babel-x.x.x.tar.gz
% mkdir babel-linux-build
% cd babel-linux-build
% ../babel-x.x.x/configure -C

Note that the directory where you build Babel should be different from the directory where you install Babel. The default install directory is /usr/local, but can be set to any directory that you have read/write access to. To change the install directory, run configure with the --prefix option. Since many people do not have root access on their machine (or prefer to install in a local directory when dealing with unfamiliar software), this option is probably the second most heavily used option for configure (first being --help, which is a good one to try also.)

At the time of this writing (1.1.0), there are two configure scripts in Babel, about 47K lines of shell script each. These configure scripts will then propagate the information they acquire to Makefiles by performing approximately 190 sed substitutions (per Makefile), to the source code by setting approximately 170 preprocessor macros in babel_config.h, and various bits of shell script in the build that do not get propagated to the install directory. The configure script does not modify any source code in Babel’s runtime system or code generator. This means that source code generated by a different Babel installation is usable as long as it gets compiled against the local babel_config.h and linked with the local Babel runtime libraries.

3.1.2  Make

The makefiles are generated by the configure script from Makefile.in templates. The configure script is generated by a tool called autoconf. The Makefile.in’s are generated from Makefile.am files by a separate, related tool called automake. We also use a tool called libtool to help with libraries. Libtool is written in shell, automake in perl, and autoconf in m4.

After a successful configuration step, if your build fails it is most likely that there is a bug in Babel, autoconf, libtool, or a library of m4 macros from any of the above. It is less likely to be an issue with automake, but possible. Perl and m4 themselves are no longer involved in the process after the configure script is produced, so while there may be a nascent bug in the files they generated, it is unlikely.

3.1.3  Make Check (Optional)

This is an exhaustive check that can take hours to complete on an average workstation. The number of actual tests run depends on the number of languages that are enabled. In general a driver and an implementation of each test is generated in each enabled language. Then each combination of driver and implementation are run (both statically linked libraries and dynamically loaded libraries, as appropriate) and tested. A test script can actually launch multiple tests, and tests can have multiple parts. At the time of this writing (babel-0.9.3) there are over 13,000 parts tested when all languages are enabled.

3.1.4  Make Install

This transfers built software to the final installation directory. Examples and tests are not installed, nor are Makefiles or dozens of other types of files. Make install also builds javadoc documentation for Babel’s code generator. Since some libraries are built with install paths in mind, libtool uses a lot of scripts to make things work in their build directory with binaries actually hidden in .lib subdirectories. Make install strips this extra scaffolding away as well.

3.1.5  Make Installcheck (Optional)

This is the same test suite as with make check. The only difference is that it is run against the code in the install directories, not the build directories.

3.2  External Software Requirements

Babel builds on a lot of available software; some optional, some required. Some we ship in our tarball, some we require users to install separately.

3.2.1  Required & Included

• Java GetOpt: This is a Java rewrite of GNU GetOpt available at http://www.urbanophile.com/arenn/hacking/download.html The Babel code generator uses this to parse command line arguments. The JAR file, download information, and licensing details are in the lib/ subdirectory of the Babel distribution.
• Xerces-J: Xerces-J is a Java implementation of SAX and DOM XML parsers available from the Apache Software Foundation at http://www.apache.org. The Babel code generator uses this for XML I/O. The JAR file, download information, and licensing details are in the lib/ subdirectory of the Babel distribution.
• libparsifal: libparsifal is a lightweight XML parser implemented in C, and Babel uses it to parse its .scl files.
• libchasmlite: Babel uses a simplified form of the Fortran array descriptor library from Chasm (see http://chasm-interop.sourceforge.net). Chasm is a language interoperability tool in its own right, but as of version 1.0.1, only the array library is considered complete. Without libchasmlite, the configuration script will disable Fortran 90/95 support.
• libltdl: The libtool dynamic loading library.

3.2.2  Required but Separate

• Unix shell & bintools: On early 64bit Linux boxes, we found it necessary to rebuild even these basic tools with all 64bit options enabled. Apparently they were originally installed with less attention to detail than necessary. Bintools includes things like cp and mv.
• C/C++ compiler: The Babel runtime library and much of the code generated by the Babel code generator will be ANSI C. So that must be available. The C++ compiler should be optional, but at the time of this writing the configure and makefiles didn’t reliably support disabling C++.
• Java: The Babel code generator is implemented in Java. One can disable the support for Java language bindings, but a working Java would still be needed for just about everything else. We generally stick with Sun’s java developer kits (available at http://java.sun.com). Others have run Babel with Kaffe and GCJ.

3.2.3  Recommended

• Python: Needed for the python language binding (obviously) and for the testing harness. Since the Linux kernel is often configured with a Python-based tool, its hard to find a Linux without python already installed. Python can be downloaded from http://www.python.org.

  One important gotcha is a special case where non-python applications create Babel objects implemented in python. In this case, the Babel runtime needs to dynamically load the python virtual machine (libpython.so). Unfortunately, python does not always build a dynamically loadable version of this library by default. If the Babel configure script cannot find a libpython.so, it will disable server-side Python support.

  At the time of this writing, Python cannot be coerced to build a libpython.so on AIX.

• NumPy: This is a scientific array python extension module. It provides native C arrays (and the ability to manipulate very big arrays) similar to python lists. Babel’s python language binding requires this extension module available at http://numpy.scipy.ord.
• Python Meta Widgets (Pmw): This is a library of GUI widgets built on top of Python’s native tcl/tk interface (tkinter). Its available on SourceForge http://pmw.sourceforge.net Pmw is only needed by the GUI in the babel-life supercomputing demo. This Babel implementation of Conway’s Game of Life is a separate tarball found in the contrib/ directory of the Babel distro. There is no test for Pmw in Babel’s configuration script.
• pthreads: Needed for Java language binding.

3.2.4  Optional

These packages are used by Babel maintainers in the course of normal development. You’ll need these only if you start rewriting code in Babel’s distribution.

• Automake: Part of GNU Autotools (see http://www.gnu.org/software/automake). Check the configure.ac file to determine exactly which version we use. The configure script will disable autoconf if it detects the slightest variation from the version we prescribe.
• Autoconf: Part of GNU Autotools (see http://www.gnu.org/software/automake). Check the configure.ac file to determine exactly which version we use. The configure script will disable autoconf if it detects the slightest variation from the version we prescribe.
• Libtool: Part of GNU Autotools (see http://www.gnu.org/software/libtool). Note that we often find need to make minor tweeks to ltmain.sh so a fresh download may generate slightly worse results on some platforms.
• m4: Contact us for a patched version that we use (we overflow buffers in the distributed version).
• JavaCC: This Java Compiler Compiler is what we use to generate the SIDL parser in Babel. If you are interested in experimenting with changing the SIDL grammar, then edit the compiler/gov/llnl/babel/parsers/sidl2/SIDLParser.jj file and rebuilt the parser with this tool. Information available at https://javacc.dev.java.net.
• H^EV^EA: This is used to generate the HTML version of our manuals (see http://hevea.inria.fr/).
• rst2man: This is used to generate man page (see http://docutils.sourceforge.net/).
• perl: Needed by automake and other bits and pieces.

Chapter 4  Basic Babel Code Generation

This chapter describes the Babel code generator and its command line options.

4.1  Babel is a Compiler

Babel is a compiler. It takes symbols and their interfaces as input and generates either code or a given textual representation. These interfaces may be specified in either Scientific Interface Definition Language (SIDL) or Extensible Markup Language (XML). The form the output takes depends upon the options specified on the command line. Refer to the Section 4.2 for details on command line options. More information on the supported bindings can be found in Part II of this document.

4.2  Command Line Options

The entire Babel code generator is written in Java and compiled into a jar file. For convenience, a small script called babel is provided that should set the appropriate environment variables and invoke the Java Virtual Machine on the jar file. To test that the script and jar file are working together properly, simply type babel --help.

Using Babel

Babel requires exactly one of the following mutually exclusive arguments on the command line unless you use the --multi option.

• --help   :   Print options to stdout.
• --version   :   Print version of Babel.
• --text=form   :   Generate text equivalent (“sidl” or “xml”) of associated package(s) or generate interface documentation with “html”.
• --client=lang   :   Generate client, or proxy, classes to access library.
• --server=lang   :   Generate the server and client classes to implement the library.
• --parse-check   :   Check the SIDL file only.

By far, the three most common uses of Babel will be to generate the Client-side proxies, Server-side implementations, and XML associated with the SIDL file. The last option is essentially used internally when the Babel runtime library is being developed.

The --multi option lets you generate multiple targets for a given set of files in a single run. Put it first on the command line, each --client or --server can have a different set of settings.

Additionally, there are a few supplemental arguments that complete the picture.

• --output-directory=dir   :   Specifies the root directory associated with the generated files. The default setting is the current working directory.
• --generate-hooks   :   Generate additional methods in the implementation files that allow developers to put additional code to be called before and after the actual method call. These hooks are useful for implementation-specific method invocation instrumentation. Their execution can be disabled at run-time.
• --generate-subdirs   :   Generates files in a directory tree matching the packaging scope of the SIDL file. This is on by default for languages that have this requirement, such as Java and Python, but off by default for languages that have no such requirement. Hence, code generation for only the latter languages (e. g. C, C++, F77, F90) is affected by this option.
• --generate-subdirs-off   :   Turn the --generate-subdirs feature off. This is useful with --multi option.
• --short-file-name   :   When the --generate-subdirs and --short-file-names options are used simultaneously, the generated file names will not include package names, just the class or interface symbol. Thus, either long or short names must be used in all clients or servers that have interdependencies; mixing short and long names will result in compile and/or runtime errors.
• --repository-path=path   :   Specifies a semicolon-separated list of directories, or URLs¹ to search for XML Type descriptions. The need for these XML types is to resolve references in the SIDL file. This option can be used multiple times on the same command line. If appropriate, the Babel script adds the default repository path to the command line before dispatching to the Java Virtual Machine.
• --no-default-repository   :   Prohibits the use of the default repository in resolving symbols.
• --rename-splicers   :   To improve some of the Babel 1.0 splicer blocks names were changed in Babel 1.4. This switch will automatically rename Babel 1.0 splicer blocks to their new Babel 1.4 names.
• --suppress-contracts   :   Refrain from generating checks associated with contracts specified in the SIDL file.
• --suppress-ior   :   Refrain from generating IOR source and header files.
• --suppress-timestamp   :   Suppresses the insertion of meta-information that could result in generated files that would otherwise not differ from prior executions on the same, unchanged input file. Typically Babel inserts meta-information such as creation time into files it generates. Although this information is useful, it does result in the creation of excessive changes when using version control systems.
• --exclude=regex   :   This options can be used multiple times. Each time you add a regular expression that will be used to exclude symbols from code generation. No code or XML will be generated for any symbol matching the user provided regular expression. This command line option requires version 1.4.0 or later of the Java runtime environment.
• --cca-mode   :   This flag changes the contents of splicer blocks to match the requirements for the Common Component Architecture (CCA). Unimplemented methods throw exceptions, and there are some extra indications for Bocca about which sections still require editing.
• --comment-local-only   :   This option reduces the amount of comments in stub C header files. It will only include the doc comments for locally defined methods. It will not include doc comments for inherited methods.
• --hide-glue   :   This option causes all non-impl files to be generated in a glue/ subdirectory. This reduces the “clutter” in the current directory.
• --hide-glue-off   :   Turn off the --hide-glue setting.
• --language-subdir   :   This options causes all generated files to be stored in a language-dependent subdirectory; if the --generate-subdirs option is also used, the language directory will be at the bottom of the hierarchy.
• --language-subdir-off   :   Turn the --language-subdir setting off.
• --make-prefix=prefix   :   The string prefix is prepended to the name of babel.make and the symbols defined inside babel.make to allow Babel to be run multiple times in a single directory without overwriting files.
• --makefile   :   This instructs Babel to generate a sample GNU Makefile named GNUmakefile. The sample GNU Makefile uses babel-config to determine the appropriate build flags. It’s meant to be a simple, example Makefile, and it will likely require editing before incorporating it in a larger project build. It may not work correctly with other options that change where files are generated such as the --hide-glue option.
• --exclude-external   :   This option causes code to be generated only for the symbols specified on the command line. If you list a SIDL file on the command line, all the symbols it contains will be included. No code is generated for symbols on which the users symbols depend. This behavior is now the default behavior, so this option is not usually required.
• --include-referenced   :   This option causes code to be generated for symbols specified on the command line and for all symbols referenced by symbols on the command line. It is the opposite behavior to --exclude-external.
• --cxx-ior-exception   :   Earlier versions of the Babel C++ bindings checked the IOR pointer in a given stub before making any calls on it. If the IOR was null, a NullIORException was thrown. It was later found that in certain cases these checks were taking an inordinent amount of time, and since C++ does not normally check pointers before dereferencing them, it was decided that this feature was out of line with the spirit of C++. However, since some code had already been written that used this feature, we could not completely eliminate the checks. Therefore, this command line option was added. Calling babel with it will generate C++ stubs with the checks in them. This option has no effect on other languages.
• --vpath=dir   :   This option sets the root directory Babel searches first when trying to load implementation files to preserve splicer block contents in the hand edited implementation files. If you are generating server-side C for a concrete class x.y.z and you used --vpath=/tmp, Babel would try to read splicer blocks from /tmp/x_y_z_Impl.h and /tmp/x_y_z_Impl.c. If it does not find either file in /tmp, it also checks the current directory. If you are using --generate-subdirs with --vpath, the vpath directory is the root of the tree, so for the example, Babel would search for /tmp/x/y/z_Impl.h and /tmp/x/y/z_Impl.c. When appropriate, Babel inserts #line directives to refer debuggers to the original file. As its name suggests, this option is useful when making vpath builds using make. Some people also use it to avoid spurious changes to the files managed by their revision control system.

Long and Short Forms

---

Table 4.1: Command Line Arguments.

SHORT FORM	LONG FORM	NOTES
-h	--help	Print options to stdout.
-v	--version	Print version of Babel.
-tform	--text=form	Generate text.
-clang	--client=lang	Generate client classes.
-slang	--server=lang	Generate server and client classes.
-p	--parse-check	Only check parsing of the SIDL file.
	--cca-mode	New splicer blocks get CCA-required content.
-i	--generate-hooks	Generate pre-/post-method hooks.
	--generate-sidl-stdlib	Regenerate the Babel runtime library.
-odir	--output-directory=dir	Root directory to contain generated files.
-g	--generate-subdirs	Generate sources in directory tree matching
		SIDL packaging.
	--generate-subdirs-off	Turn off generate-subdirs.
-m	--make-prefix=prefix	Prepend prefix to names for babel.make.
	--makefile	Generate a simple GNU Makefile.
	--multi	Generate multiple targets in a single run.
-Rpath	--repository-path=path	Use specified XML repository(ies) to resolve
		symbols.
-eregex	--exclude=regex	Do not generate output for matching symbol(s).
	--no-default-repository	Do not use the default repository to resolve
		symbols.
	--rename-splicers	Rename Babel 1.0 splicer blocks to their 1.4 names.
	--suppress-contracts	Don’t generate contract checks in IOR files.
	--suppress-ior	Don’t generate IOR files.
	--suppress-stubs	Don’t generate client-side stub files.
	--suppress-timestamp	Suppress time-related metadata generation.
	--comment-local-only	Reduce doc comments in C stub header.
-E	--exclude-external	Do not generate code for dependencies.
	--include-referenced	Generate code for dependencies.
-u	--hide-glue	Put glue code in a subdirectory.
	--hide-glue-off	Turn off hide-glue.
-l	--language-subdir	Put code in a language dependent directory.
	--language-subdir-off	Turn off language-subdir.
-x	--cxx-ior-exception	Include Null IOR checks in C++ Stubs.
-V	--vpath	Set the impl (splicer block) root directory.

---

So far, we’ve shown described the long forms of command line arguments, starting with two hyphens “--”. There are also short forms for many of the more frequently used commands. See Table 4.1 for details.

Examples

To create a new XML version of a SIDL file, use the following command:

% babel -tXML -omydepot mystuff.sidl

To exclude code generation for types whose name begins with “MPI.”, use the following command:

% babel -sC++ –exclude=’^MPI\.’ mystuff.sidl

Now suppose a developer wants to implement a library in C++ that corresponds to these types in the SIDL file.

% babel -E -sC++ mystuff.sidl

Alternatively, the developer could also create C++ implementation files based on the XML repository. In this case, a list of symbols to be implemented would need to be specified. Assuming that all of the types are in a package called “mystuff”, the following command can be issued:

% babel -E -sC++ -Rmydepot mystuff

Now suppose a second developer wants to extend this software. A second SIDL file is created then the implementation files in Fortran 90/95 are generated with the following command:

% babel -E -sf90 -Rmydepot newstuff.sidl

A user now can download both SIDL files and create their Python bindings to use both libraries with the following command:

% babel -cPython -Rhttp://localhost/mystuff/mydepot;
http://www.otherhost.com/newstuff mystuff newstuff

Finally, to generate SIDL files for each package based on the XML stored in the repository, the following command is used:

% babel -tSIDL -Rhttp://localhost/mystuff/mydepot;
http://www.otherhost.com/newstuff mystuff newstuff

1

URLs have colons in them, so this path has to be semi-colon separated, even though UNIX paths are traditionally colon separated.

Chapter 5  Hello World Tutorial

For the things we have to learn before we can do them, we learn by doing them.
— Aristotle (384 BCE – 322 BCE)

5.1  Introduction

This tutorial guides you through the process of writing the classic “Hello World!” example using the Babel tools. In the process, you will learn that the most vexing problem is getting the compiler and linker flags set up properly. Closely followed by the hassles of encoding this information in portable Makefiles.

This section offers a spectrum of possible solutions, from the minimalist but not portable, to the very robust and portable but not trivial, and a few options in between. The following sections start from the simplest setup, and work up in terms of complexity and features.

Assuming Babel is built, installed and your PATH environment variable has been set, we need to set up a few directories for this exercise. One can verify it was built and installed properly by going to the directory where it was built and typing make installcheck. (Warning: It can take a few hours on a good workstation for Babel’s exhaustive tests to complete.) To verify Babel is in your path, simply try running it with the --version or --help option. Now pick a starting directory and issue the following commands to create some directories

% mkdir -p hello/minimal/libCxx
% mkdir -p hello/minimal/libF90
% cd hello

Now we write a SIDL file to describe the calling interface. It will be used by the Babel tools to generate glue code that hooks together different programming languages. A complete description of SIDL can be found in Chapter 6. We will use the same SIDL file for several different coding exercises and Makefile setups, so the SIDL file need not be large or complex for our purposes.

For this particular application, we will write a SIDL file that contains a class World in a package Hello. Method getMsg() in class World returns a string containing the traditional computer greeting. Using your favorite text editor, create a file called hello.sidl in the hello/ directory containing the following:

The package statement provides a scope (or namespace) for class World, which contains only one method, getMsg(). The version clause of the statement identifies this as version 1.0 of the Hello package.

5.2  Minimal Makefiles

Babel has the ability to generate simple, minimal GNU Makefiles using the --makefile command-line option. The generated GNU Makefiles require GNU make and are intended primarily as an aid to get you started. They assume that babel and babel-config are in your path.

5.2.1  Writing the C++ Implementation

We will write the C++ implementation in the minimal/libCxx/ subdirectory of hello/. The first step is to run the Babel code generator on the SIDL file and have it generate the appropriate code. The simplified command to generate the Babel library code (assuming Babel is in your PATH) is ¹:

% cd minimal/libCxx
% babel -sC++ –makefile ../../hello.sidl

In this Babel command, the “-sC++” flag, or its long form “--server=C++”, indicates that we wish to generate C++ bindings for an implementation². This command will generate a large number of C and C++ header and source files. It is often surprising to newcomers just how much code is generated by Babel. Rest assured, each file has a purpose and there is a lot of important things being done as efficiently as possible under the hood.

Files are named after the fully-qualified class-name. For instance, a package Hello and class World would have a fully qualified name (in SIDL) as Hello.World. This corresponds to file names beginning with Hello_World³. For each class, there will be files with _IOR, _Skel, or _Impl appended after the fully qualified name. Stubs often go without the _Stub suffix. IOR files are always in ANSI C (source and headers), containing Babel’s Intermediate Object Representation. Impl files contain the actual implementation, and can be in any language that Babel supports, in this case, they’re C++ files. Impl files are the only files that a developer need look at or touch after generating code from the SIDL source. Skel files perform translations between the IORs and the Impls. In some cases (like Fortran) the Skels are split into a few files: some in C, some in the Impl language. In the case of C++, the Skels are pure C++ code wrapped in extern "C" {} declarations. If the file is neither an IOR, Skel, nor Impl, then it is likely a Stub. Stubs are the proxy classes of Babel, performing translations between the caller language and the IOR. Finally, the file babel.make is a Makefile fragment that is used by GNUmakefile or to simplify making your own custom build. You may ignore the babel.make file if you wish. There are also babel.make.depends and babel.make.package files. These were added by external contributors, and we will ignore them in this document.

The only files that should be modified by the developer (that’s you since you’re implementing Hello World) are the “Impls”, which are in this case files ending with _Impl.hxx or _Impl.cxx Babel generates these implementation files as a starting point for developers. These files will contain the implementation of the Hello library. Every implementation file contains many pairs of comment “splicer” lines such lines 4 and 6 in the following sample:

Any modifications between these splicer lines will be saved after subsequent invocations of the Babel tool. Any changes outside the splicer lines will be lost. This splicer feature was developed to make it easy to do incremental development using Babel. By keeping your edits within the splicer blocks, you can add new methods to the hello.sidl file and rerun Babel without the loss of your previous method implementations. You shouldn’t ever need to edit the file outside the splicer blocks.

For our hello application, the implementation is trivial. Add the following return statement between the splicer lines in the lib/Hello_World_Impl.cxx file:

The following is a listing of the generated GNUmakefile excluding the boilerplate copyright notice. It uses some of the tools installed along with Babel to automated generating a static and shared library provided that the machine supports both. The babel-config provides information about which compilers and compiler flags to use, and babel-libtool manages the building of object files and libraries.

The details of this makefile deserve careful explanation.

line 1:

babel.make is a file that Babel generates when it generates code. It defines some standard names so our makefiles don’t have to know every SIDL type declared in the file.

line 3:

LIBNAME defines the name of the library file that will be generated. This is the only line that I had to edit in the babel-generated GNUmakefile.

line 7:

Use EXTRAFLAGS to define additional compile flags to be used when compiling files. For this example, it should be empty.

line 9:

EXTRALIBS should hold any extra libraries needed for your application. For this example, it should be empty.

line 11:

The VERSION should be three numbers separated by periods.

line 13:

The PREFIX is for libraries that will be installed.

line 21–end:

This part of the GNUmakefile works from the definitions above and usually does not require changes unless you are incorporating it into a more complex build system.

line 33:

The first build target in a Makefile is also the default target. Common convention is to make this target’s name “all.”

lines 35–40:

Note that we use a script called babel-config to hand us some information. This tool is very useful for getting the same information that Babel’s configure script was given as Babel configuring itself. Increasingly, it is being used to also get information about tools and flags used in Babel’s makefiles, and its utility for getting at this level of information is limited…mostly because we rely on a multilayered stack of tools and some are less forthcoming than others.

lines 42–45:

Here you see some of the variables defined in babel.make and some fancy suffix substitution to define STUBOBJS, IOROBJS, SKELOBJS, and IMPLOBJS.

lines 53:

This is the rule to combine the .o files into a static and dynamic library using babel-libtool.

line 88:

This is a often misunderstood detail. To override the default suffix rules, one must give the list of new suffices to consider.

line 90–94:

Here we start to override make’s default suffix rules for converting C and C++ sourcecode into .o files.

lines 96 & 99:

How you go about various levels of cleanliness in your makefiles largely depends on matters of taste. The important point here is what is not removed. One thing not cleaned up is babel.make it is generated by Babel, but the makefile won’t work without the file present because of the include in line 5. Another important thing to not remove is the Impl files, since they have hand-edited regions in the generated file.

line 103–129:

Here we define some simple rules for installing libraries into standard system locations.

line 131:

Technically, any phony targets like “clean” and “new” are supposed to be listed in this variable. Many makefile implementations will work well if you skip this line, but.

With the GNUmakefile in place we can simply go to that directory and build everything by typing make.

5.2.2  Writing the Fortran 90/95 Implementation

Before writing the client, let’s generate a Fortran implementation as well. It is highly instructive to see how the makefiles differ between the different language bindings. From within the minimal/libCxx directory we do.

% cd ../libF90
% babel –makefile -sF90 ../../hello.sidl

This time there’s even more files generated (Fortran 90/95 bindings are harder after all), and we need to add our implementation to the Hello_World_Impl.F90 file. The modified code will look like this.

Note that the C function appears as a subroutine in Fortran. What was the return value appears here as the argument retval (line 5). For Fortran 90/95 there are also two splicer blocks per subroutine, one for use statements (lines 11–13) and another for the actual implementation (lines 19–21). This is where we put our implementation by setting retval to the string we want.

There are important differences in this Makefile from the C++ implementation, so we reproduce it in its entirety here.

line 1:

Again Babel will generate a babel.make file, but we will see that its contents are different.

line 3:

The name of the library will be libhello.la again. This is the only line that I had to edit in the babel-generated GNUmakefile.

lines 7–19:

These variables have the same meanings as above. EXTRAFLAGS are extra compile flags, and EXTRALIBS defines extra libraries to list when linkings. PREFIX defines where the library should be installed.

lines 35–43:

Note that we use babel-config to generate the proper flag for the preprocessor to find the Babel Fortran headers, and the compiler to find the Babel MOD files.

lines 45–56:

Are building a $(OBJS) variable like before, but this time we see suffix substitutions for more kinds of files.

lines 63–67:

The order that files are compiled is important because Fortran 90/95’s use of MOD files⁴ makes the ordering of these items very important. (Not Babel’s fault, blame the Fortran 90/95 language designers.) C/C++ has no such constraint on the order that individual units of compilation are performed. As long as Fortran 90/95 programmers stick with the ordering shown in these lines, they should not encounter compiler complaints about dependent MOD files not found.

lines 110–114:

This bit of code admittedly looks very strange, but the explanation is simple. We preprocess our Fortran 90/95 source to workaround the 31 character limit specified in the language. Check out Chapter 11 for more details about this issue.

Again, we simply type make, and should end up with another libhello.la file.

5.2.3  Writing the C Client

Now, finally, we are ready to write a client. For this exercise, we wrote our driver in C and built two executables; each one linking in one of the two implementation libraries. We will put our driver in the minimal/ directory (which happens to be the parent directory of where the C++ and Fortran 90/95 implementations are, though this detail is only relevant to makefile construction). From our Fortran 90/95 subdirectory, we go up one and generate the client-side C bindings.

% cd ..
% babel –makefile -cC ../hello.sidl

The “-cC” flag, or its equivalent long-form “--client=C”, tells the Babel code generator to create only the C stub calling code, not the entire library implementation.

There are a few details worth noting here. The C bindings generate function names by combining packages, classes, and method names with underscores (e. g. Hello_World_getMsg(). Whenever you see double underscores in Babel generated symbols, they indicate something built-in to (and sometimes specific to) the language binding. The _create() method is built-in to every instantiatable class defined in SIDL, triggering the creation of Babel internal data structures as well as the constructor of the actual object implementation.

The code listing below shows a well crafted driver with full error checking. To try this example, use your favorite text editor to copy this text into a file named main.c.

As with other examples, we will go through this one line by line. It is important to note that nowhere in this file is any indication of what language the Babel object is implemented in. When you see the makefile, we will show that this code can be linked against multiple implementations in different languages.

line 2:

This line includes the C stub for the Hello.World type.

line 3:

We also include the C stub for the sidl.BaseInterface type which all classes and interfaces ultimately inherit from. In C, we often use this type to hold the exception argument.

line 4:

There is no sidl.Exception type. This header actually introduces some useful macros for dealing with exception handling in C.

line 13:

This is where the object is _create()’ed. Note that the creation may fail, so we use the SIDL_CHECK macro introduced from sidl_Exception.h to test the exception and goto EXIT (line 39), if necessary.

line 21:

With a live reference to the object, we now try to get the message out of it. Note that we check if the exception is thrown and if the string is NULL.

line 29:

Once we have the message, we can dispose of our reference to the object.

line 32:

Print the message

line 35:

Free the string. Return values have the same semantics as out parameters which is the caller always recieves a reference count and is obligied to dispose of it when done.

line 37:

Normal termination.

lines 39–56:

This is exception handling code. Its hard to imagine so many possibilities for failure in our little example, but it is useful to see how exception classes can be cast to appropriate types (line 43), and be queried for both original error message and the trace of the call stack from which it was thrown.

line 42:

Note that Babel generated methods always throw exceptions, but in exception handling code, we often ignore them. Do not call SIDL_CHECK after the EXIT as this can easily result in an infinite loop.

Now we need to edit the GNUmakefile that builds the code in this directory and links it with the C++ or Fortran 90/95 implementations in the two subdirectories. This case requires more editing that the previous two examples.

line 1:

Again we include the Babel-generated makefile fragment. Again we see that its contents depend on the language being generated.

line 3:

Here we edit the name to be client.

lines 5–19:

These have the same meanings as in the examples above.

lines 34–43:

Here we must modify the all target definition and add lines to link runC2Cxx and runC2F90. Note that when linking C to C++, we must use the C++ compiler.

At last, we can make the two executables and run them.

% make all
% ./runC2Cxx
Hello from C++!
% ./runC2F90
Hello from Fortran 90/95!

5.3  Portable Makefiles: using babel-config

Since Babelized software must be built the same way that Babel itself was configured, it seems reasonable to lean on babel-config quite heavily. By now you are probably wondering how many secrets babel-config holds and can provide on request. The simplest way to find out is to ask it. (Though you may get a slightly different result than what is shown here depending on the version of Babel.)

% babel-config --dump-vars | wc -l
128

babel-config can provide a wealth of information determined by Babel during its configuration and installation. Even if you do not use the GNUmakefile’s that Babel can generate, you will likely end up using babel-config to determine important information about Babel’s installation

5.4  Final Remarks

Congratulations! You are now ready to develop a parallel scalable linear solver package.

The preceding process may seem to be the most complicated way to write the world’s simplest program but, of course, the same process will also work for significantly more complex applications. “Hello World” is small enough to experiment with in the language of your choice. Parallel, multithreaded, scientific simulation codes are another matter entirely.

1

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

2

You can also try the “--help” flag to list all of the Babel command-line options.

3

Note: dots are converted to underscores for file naming.

4

A kind of precompiled header.

Chapter 6  SIDL Basics

6.1  Introduction

This chapter describes the basics of the Scientific Interface Definition Language (SIDL). The goal is to provide sufficient information to enable most library and component developers to begin using SIDL to wrap their software. It begins with an overview of SIDL files followed by an introduction to the fundamental data types. More complex topics such as the object arrays, exceptions, objects, and the XML repository are then addressed.

6.2  SIDL Files

SIDL files are human-readable, language- and platform- independent interface specifications for objects and their methods. SIDL allows you to specify classes, interfaces, and the methods therein. All methods defined in SIDL are public, since the developer is writing them as part of an interface description. Any data you wish a SIDL object to hold is not declared in the SIDL file, and is private. Data should be placed in the implementation skeleton files, and cannot be publicly exported.

Babel reads the SIDL files to generate the appropriate programming language bindings. These bindings, in the form of stub, intermediate object representation (IOR), and implementation skeleton sources, provide the basis for language interoperable software using Babel. In addition, SIDL files are used to populate the XML symbol repository that can serve as an alternate source of interface specifications during the generation of programming language bindings.

Basic Structure

The basic structure of a SIDL file is illustrated below.

The main elements are packages, interfaces, classes, methods, types, and contract clauses. For a more detailed description, refer to Appendix B.

Packages

provide a mechanism for specifying name space hierarchies. That is, it enables grouping sets of interface and/or class descriptions as well as nested packages. Identified by the package keyword, packages have a scoped name that consists of one or more identifiers, or name strings, separated by a period (“.”). A package can contain multiple interfaces, classes and nested packages. By default, packages are now re-entrant. In order to make them non-re-entrant, they must be declared as final.

Interfaces

define a set of methods that a caller can invoke on an object of a class that implements the methods. Multiple inheritance of interfaces is supported, which means an interface or a class can be derived from one or more interfaces.

Classes

also define a set of methods that a caller can invoke on an object. A class can extend only one other class but it can implement multiple interfaces. So we have single inheritance of classes and multiple inheritance of interfaces.

Methods

define services that are available for invocation by a caller. The signature of the method consists of the return type, identifier, arguments, and exceptions. Each parameter has a type and a mode. The mode indicates whether the value of the specified type is passed from caller to callee (in), from callee to caller (out), or both (inout). All methods are implicitly capable of throwing a sidl.RuntimeException exception. A sidl.RuntimeException is used to indicate an error in the Babel generated code or potentially a network exception. Each additional exception that a method can throw when it detects an error must be listed. These exceptions can be either interfaces or classes so long as they inherit from sidl.BaseException. For a default implementation of the exception interfaces, the exception classes should extend sidl.SIDLException. Methods and parameter passing modes are discussed in greater detail in Section 6.7.

Types

are used to constrain the the values of parameters, exceptions, and return values associated with methods. SIDL supports basic types such as int, bool, and long as well as strings, complex numbers, classes, and arrays.

Contract clauses

are used to define properties that must hold before and/or after method invocation.

Comments and Doc-Comments

SIDL has the same commenting style as C++/Java and even has a special documentation comment (so called doc-comment) similar to those used in Javadoc. One can embed comments anywhere in their SIDL file. Documentation comments should immediately precede the class, interface, or method with which they are associated. Babel replicates documentation comments in the files it generates. It does not replicate plain comments.

Consider the above SIDL file fragment.

1. This comment is a regular multi-line comment that is delimited by a slash-star , star-slash (“/*”, “*/”) pair.
2. This is a single-line comment that starts with a double slash “//” and continues to the end of the line.
3. This comment is the same as # 1 except that it is completely contained on a single line. It can be embedded in the middle of a line anywhere a space naturally occurs.
4. This is a documentation comment. In keeping with Javadoc, Doc++, and other tools, it is delimited by slash-star-star and star-slash (“/**”, “*/”) combinations. Documentation comments are important because their contents are preserved by Babel in the corresponding generated files. Doc-comments must directly precede the interface, class, or method that they document.
5. This is a multi-line variant of a doc-comment. Note that initial asterisks on a line are assumed to be for human readers only and are discarded by Babel when it reads in the text. The multi-line doc-comment is the preferred way of documenting SIDL.

Packages and Versions

SIDL has both a packaging and versioning mechanism built in. Packages are essentially named scopes, serving a similar function as Java packages or C++ namespaces. Versions are decimal separated integer values where it is assumed larger numbers imply more recent versions. All classes and interfaces in that package get that same version number. If subpackages are specified, they can have their own version number assigned. If a package is declared without a version, it can only contain other packages. If a package declares interfaces or classes, a version number for that package is required.

This SIDL file represents the minimum needed for each and every SIDL file. The package statement defines a scope where all classes within the package must reside. Since no version clause is included, the version number defaults to 0.

Packages can be nested. This is shown in the example below. The version numbers assigned to all the types is determined by the package, or subpackage, in which it resides. In the design of the SIDL file, remember that some languages get very long function names from excessively nested packages or excessively long package names.

In SIDL you can use as much or as little of a type name as necessary to uniquely identify it. If absolute specificity is required, a leading dot can be used to identify the global (top) package.

External types can be expressed in one of two ways. The fully scoped external type can be used anywhere in the class description. Alternatively, an import statement can be used to put the type in the local package-space. import statements can request a specific version of the package, if that version is not found, Babel will print an error. If no version is specified, Babel will take whatever version it is being run on. Babel can not be run on two versions of a given package at the same time, even if you only import or require one of them.

Another way to restrict the package version you use is the restrict statement. restrict does not import the package, but if you do later import the package or refer to something in that package by it’s fully scoped name, Babel will guarantee that the correct version of the package will be used. Also note that all restrict statements must come before the first import statement.

Below is a sample SIDL file, that should help bring all of these concepts together.

Re-entrant Packages

By default, SIDL packages are re-entrant. This means that Babel allows sub-packages to be broken into separate files, but you’d still have to run Babel on all the files at the same time. Here’s how it works.

First define the outermost package in a file.

Then define a sub-package in a second file.

Note that both files begin with the identical version statement. Now as long as you run Babel on both SIDL files at the same time (with the outermost one first on the commandline), all is fine.

This works because the package statement takes a scoped identifier as an argument. As long as Babel knows that a package mypkg exists, it can handle a new package called subpkg. (This would also work if subpkg were a class. Version statements require an identifier for the outermost package. Since packages cannot have dots “.” in their names, the only dots in version statements should appear at the numbers, not the package names.

Running the second file without the first will (and should) generate an error since the enclosing package was not declared. Re-entrance should be used judiciously. This feature may be disabled by labeling a given package as final.

The From Clause

The from clause is a special SIDL statement that allows an implementor of multiple interfaces to add or rename the extensions of conflicting methods from interfaces. However, only method extensions can be changed, and the methods must have different signatures. For example, one can change the name of conflicting methods from two interfaces:

Or change the name of an interface method that conflicts with your inherited class methods:

But it doesn’t work for methods that have the same signature:

6.3  Fundamental Types

---

Table 6.1: SIDL Types

SIDL TYPE	SIZE (BITS)
bool	1
char	8
int	32
long	64
float	32
double	64
fcomplex	64
dcomplex	128
opaque	64
string	varies
enum	32
interface	varies
class	varies
array<Type,Dim>	varies
array< >	varies
rarray<Type,Dim>(index variables)	varies

---

Table 6.1 briefly shows the different data types that are supported in Babel. Refer to each chapter for the language specific bindings for each SIDL type. The “S” in SIDL stands for “Scientific.” This emphasis is reflected in the fundamental support for complex numbers (fcomplex and dcomplex) and dynamic multidimensional arrays (array<Type,Dim>).

C++ developers looking at the SIDL syntax for arrays, might think that SIDL is a templated IDL, but this is not so. Although the syntax for SIDL arrays looks like a template, it is specific only to the array type. Developers cannot create templated classes or methods in SIDL.

Rationale: Although C++ templates are a very powerful programming mechanism, they apply only to C++. For Babel to implement similar hashing routines, method names in languages other than C++ would become prohibitively (thousands of characters) long. Moreover, this C++ template hashing mechanism is compiler specific so while C++ is very good at hiding the expanded template names (unless there is an error to report) we would have to add babel C++ bindings on a compiler by compiler basis.

Discussion of the various types is broken up into sections. Numeric types such as bool, char, int, long, float, double, fcomplex, dcomplex, strings, as well as information about enumerated types and the opaque type are all covered in this Subsection 6.3.

Information about extended types such as Interfaces and Classes along with the methods they contain are described in Section 6.7, and Section 6.4 covers Array.

Numeric Types

The SIDL types bool, char, int, long, float, double, fcomplex, and dcomplex are the smallest and easiest data types to transfer between languages transparently. They all have a fixed size and can just as reasonably be copied as passed by reference.

Most languages natively support all of these data types (though perhaps less so with complex types). There are a few notable exceptions that may be of interest.

ANSI C does not define the size of int and long, only that the latter be at least as big as the former. As of the C99 standard, there are types int32_t and int64_t that are signed integers that explicitly support a fixed number of bits. Most compilers already have these symbols defined appropriately in sys/types.h (pre C99 standard) or inttypes.h.

Python defines its int and long to be equivalent to C, and therefore suffers the same platform dependent integer size problem with less flexibility for a workaround. It is not uncommon for regression tests involving longs and Python to fail on certain platforms. Python 2.2 has a patch to make SIDL long support better.

Strings

Strings are an interesting datatype because they are fundamental to many pieces of software, but represented differently by practically every single programming language. Strings can have a high overhead to support language interoperability because there is invariably so much copying involved.

fortran 77 and Fortran 90/95 support for strings is limited to a predetermined buffer size. Since the results of a string assignment into that buffer in Fortran does not propagate the length of the string, trailing whitespace is always trimmed for any string begin passed out from a Fortran implementation.

Opaque

The opaque type is dangerous and rarely useful. However, there are particular times when an opaque type is the only way to solve a problem; for example, it is one of the few portable ways to implement an object with state in fortran 77. When a SIDL file uses an opaque type, Babel guarantees only bits will be relayed exactly between caller and callee. If there is a need to pass more information than an opaque provides, than the developer can simply pass a pointer to that information.

Use of a opaque carries a heavy penalty. Method calls with opaque types in the argument list (or return type) are restricted to in-process calls only.

Rationale: Since opaque is typically used for a pointer to memory, this sequence of bits has no meaning outside of its own process space.

Enumerations

An enumeration is typically used in programming languages to specify a limited range of states to enable dealing with them by names instead of hard-coded values. For language interoperability purposes — especially to support this concept on languages with no native support — we’ve had to create specific rules for the integer values associated with enumerated types.

Above is a sample of enumerations taken directly from our regression tests. It defines a package enumSample that contains three enumerations. C/C++ developers will find the syntax very familiar. When defining an enumeration, the actual integer values assigned can be undefined, completely defined, or partially defined.

SIDL defines the following rules for adding integer values to enumerated states that don’t have a value explicitly defined.

1. Error if two states are explicitly assigned the same value
2. Assign all explicit values to their named state.
3. Assign smallest unused non-negative value to first unassigned state in enumeration.
4. Repeat 3 until all states have assigned (unique) values.

To verify the application of these rules, the enumSample.number enumeration will have the following values assigned to its states: NotZero=2, NotOne=3, zero=0; one=1, negOne=-1, notNeg=4.

6.4  Arrays

Support for multi-dimensional arrays is one of the features that separates SIDL/Babel language interoperability from Microsoft’s COM/DCOM and the OMG’s CORBA. SIDL supports two kinds of arrays: normal and raw. Normal SIDL arrays provide all the features of a normal SIDL type, while raw SIDL arrays, called r-arrays, exist to provide more efficient, lower level access to numeric arrays. 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/95.

The SIDL array API and data structure can be used in client code to prepare arguments for passing to a SIDL method. It is used inside the implementation code to get data and meta-data from incoming array arguments. The remainder of this section will focus on the C API for arrays because it is the basis for the other language APIs.

SIDL Arrays

Normal SIDL arrays provide all the features of a normal SIDL type. They are meant to generalize the array types built into many languages. They are not parallel array classes or particularly sophisticated, but are very, very general. It is expected that developers requiring parallel array libraries build them on top of the SIDL array type.

Characteristics of normal SIDL arrays are:

• reference counted;
• can be passed as in, inout, or out parameters;
• can be returned from a method;
• can be allocated or borrowed;
• can be set to NULL; and
• can be “row-major” or “column-major”.

Generic Arrays

The design of the (normal) array data structure enables the concept of a generic array, an array whose data type and dimension are unspecified. In SIDL, a generic array is indicated with the type array< >. There is no type or dimension information between the < and >.

Generic arrays are useful for making interfaces that are very flexible without requiring numerous methods to be defined. For example, if you were writing an interface to serialize an array, you could write one method void serialize(in array< > array); to handle an array of any type or dimension. Without generic arrays, you would have to define 77 different serialize methods to handle each possible array type and dimension.

In C, you can use the macro API to determine the dimension, bounds on each dimension and stride for a generic array. All other languages except Python provide a function API to determine the same information for a generic array.

Starting with Babel 1.1.0, Babel’s Python binding now uses either the Python NumPy or Numeric Python array API. This switch in Babel follows a switch in the Python community where the Python community has deprecated Numeric Python and appointed NumPy as its successor. If you need examples about how to write code that can work with either Python array API look at Babel’s array regression tests, arrays and ordering.

The function API for generic arrays includes the following methods: addRef, smartCopy, deleteRef, dimen, lower, upper, length, stride, isColumnOrder, isRowOrder, and type. With the exception of type, these methods have all been presented above. The name of the method has the type left empty. Where the name for addRef in C on a double array is sidl_double_array_addRef, its name is sidl__array_addRef for a generic array. Note, there are two underscores between sidl and array in the generic array case.

The type method is defined as follows in the case of C.

It returns a value that indicates what the underlying type of the array actually is. The return value is either zero or one of the values in sidl_array_type.

Once you’ve discovered the underlying type of the generic array, you can safely cast its pointer to the actual pointer type (in languages like C). Each language binding provides a way to cast generic array pointers to specific types and vice versa.

In the case of a sidl_interface_array, you can case the array to an array of sidl.BaseInterface interface references. Your code should treat it as such. You can downcast individual elements of the array as you need. Your code should consider the possibility that downcasting may fail. Babel can only guarantee that the elements of the array are sidl.BaseInterface’s.

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 available in C, C++, fortran 77, Fortran 90/95 and Fortran 2003/2008. In all other languages R-arrays are implemented as regular SIDL arrays with no particular performance advantage.

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.

Rationale: The way r-arrays are passed to the server-side code, particularly fortran 77, makes it impossible for them to be allocated or deallocated. This makes out and return values impossible. Because the data has to be accessible directly from fortran 77 without any additional meta-data, the array data must be in column-major order.

Arrays of char are not currently supported for r-arrays because in some languages characters are treated as 16-bit Unicode characters.

The advantages of r-arrays include:

• Arrays appear more “natural” in C, C++, fortran 77, Fortran 90/95 and future low level languages.
• Developers need less or no code to translate between their array data structure and SIDL’s array data structure.
• SIDL generated APIs can have signatures very similar if not identical to well known legacy APIs.
• Less performance overhead because r-arrays can avoid a call to malloc and free.

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 a method to solve one of the fundamental problems of linear algebra, A x = b:

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/95 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.

SIDL Language Features

As of release 0.6.5, interface definitions can specify that an array argument or return value must have a particular ordering for a method. The type array<int, 2, row-major> indicates a dense, ¹ two-dimensional array of 32 bit integers in row-major order; and likewise, the type array<int, 2, column-major> indicates an dense array in column-major order. Some numerical routines can only provide high performance with a particular type of array. The ordering is part of the interface definition to give clients the information they need to use the underlying code efficiently. The ordering specification is optional.

For one-dimensional arrays, specifying row-major or column-major allows you to specify that the array must be dense, that is stride 1. Otherwise, for one-dimensional arrays row-major and column-major are identical.

If you pass an array into a method and the array does not have the specified ordering, the skeleton code will make a copy of the array with the required ordering and pass the copy to the method. This copying is necessary for correctness, but it will cause a decrease in performance. The implementor of the method can count on an incoming array to have the required ordering.

For out parameters and return values, an ordering specification means that the method promises to return an array with the specified ordering. The implementation should create the out arrays with the proper ordering; because if it does not, the skeleton code will have to copy the outgoing array into a new array with the required ordering.

For inout parameters, an ordering specification means the ordering specification will be enforced by the skeleton code for the incoming and outgoing array value.

At the time of writing this, the ordering constraints are enforced for Python implementation because Python uses NumPy or Numeric Python arrays, so Babel cannot control the array ordering as fully. The Python skeletons do force outgoing arrays (i. e., arrays passed back from Python) to have the required ordering.

Independent and borrowed arrays

From a memory perspective, there are two main kinds of arrays: independent and borrowed. The independent arrays owns and manages its data. It allocates space for the array elements when the array is created, and it deallocates that space when the array is finally destroyed.

The borrowed array does not own or manage its data. It borrows its array element data from another source that it cannot manage, and it only allocates space for the index bounds and stride information. The rationale for borrowed arrays is to allow data from another source to temporarily appear as a SIDL array without requiring data be copied.

If you slice an independent array, the resulting array is also considered independent even though it borrows data from the original independent array. The resulting array can still manage its data by retaining a reference to the original array; hence, its element data cannot disappear until the resulting array is destroyed. If you slice a borrowed array, the resulting array is also borrowed because like its original array, it doesn’t manage the underlying data.

In the Babel generated code, r-arrays are converted to borrowed arrays. These borrowed arrays are allocated on the stack rather than on the heap to improve performance of r-arrays.

The Life of an Array

The existence of borrowed arrays causes the arrays to deviate from the normal reference counting pattern. You may recall that all arrays are reference counted, and an array’s resources are reclaimed when the reference count goes to zero. However, a borrowed array’s array element data will disappear whenever the source of the borrowed data determines that it should regardless of the reference count in corresponding the SIDL array. This behavior means that developers should consider any SIDL array that they did not create themselves, for example incoming arguments to methods, as potential borrowed arrays. When a method wants to keep a copy of an array that might be a borrowed array, it should use the smartCopy method documented below.

Here are some rules of thumb about the use of borrowed arrays:

• The creator of a borrowed array should guarantee that the data for the borrowed array will exist through the duration of any method calls using the borrowed array.
• Methods should not return a borrowed array as a return value or out parameter unless the method can guarantee that the array element data will be available until the process shuts down.
• There is a negligible performance cost when using smartCopy when the array is not borrowed, and there is a huge correctness benefit when the array is borrowed.

The NULL Array

NULL is a special array reference value that refers to no array. It’s used to indicate that an array reference currently points to nothing. The way you refer to NULL varies from language to language, but the concept is the same. In C++ and fortran 77, 0 (numeral zero) is the value of the NULL array. In C, the preprocessor symbol NULL is the value for the NULL array. In Python, it’s the special constant None, and in Java it’s null. In Fortran 90/95, there is a function set_null, to initialize a pointer to the NULL value, and there is a logical function is_null to test whether an array is equal to NULL.

The Language Bindings

The C++ binding for array provides access to the C API in case you need to take the gloves off and revel in the data directly. But the C++ binding also provides a templated wrapper class to provide a more natural look and feel for C++ programmers.

In some cases, the Python binding for arrays must copy SIDL arrays to/from NumPy or Numeric Python arrays; it should not happen for normally strided arrays except when an ordering constraint requires it. Arrays in Python don’t have the SIDL methods available. They just have the NumPy or Numeric Python API available.

The fortran 77 API mimics the C API; all the C functions have been Fortran’ified and have _f appended to their names. The Fortran 90/95 API uses function overloading to allow programmers to use the short array method names.

The Array API

In the following presentation, we use the SIDL double type; however, everything in this section applies to all types except where noted. The basic types are in the SIDL namespace. Table 6.2 shows the prefix for SIDL base types and the actual value type held by the array...

---

Table 6.2: SIDL types to array function prefixes

SIDL TYPE	ARRAY FUNCTION PREFIX	VALUE TYPE
bool	sidl_bool	sidl_bool
char	sidl_char	char
dcomplex	sidl_dcomplex	struct sidl_dcomplex
double	sidl_double	double
fcomplex	sidl_fcomplex	struct sidl_fcomplex
float	sidl_float	float
int	sidl_int	int32_t
long	sidl_long	int64_t
opaque	sidl_opaque	void *
string	sidl_string	char *

---

For arrays of interfaces or classes, the name of the array function prefix is derived from the fully qualified type name. For example, for the type sidl.BaseClass, the array functions all begin with sidl_BaseClass. For sidl.BaseInterface, they all begin with sidl_BaseInterface.

When you add an object or interface to an array, the reference count of the element being overwritten is decremented, and the reference count of the element being added is incremented. When you get an object or interface from an array, the caller owns the returned reference.

For arrays of strings when you add a string to any array, the array will store a copy of the string. When you retrieve a string from an array, you will receive a copy of the string. You should sidl_String_free the returned string when you are done with it.

When you create an array of interfaces, classes, or strings, all elements of the array are initialized to NULL. Other arrays are not initialized. When an array of interfaces, classes, or strings is destroyed, it releases any held references in the case of objects or interfaces. In the case of strings, it frees any non-NULL pointers.

The name of the data structure that holds the array if double is struct sidl_double__array. For some types, the data structure is an opaque type, and for others, it is defined in a public C header file.

---

Table 6.3: SIDL Array Functions

SHORT NAME	DESCRIPTION
createCol	Creates a column-major order SIDL array
createRow	Creates a row-major order SIDL array
create1d	Creates a dense one-dimensional SIDL array
create2dCol	Creates a dense, column-major, two-dimensional SIDL array
create2dRow	Creates a dense, column-major, two-dimensional SIDL array
slice	Creates a sub-array of another array. Takes parameters to define array properties.
borrow	Makes a SIDL array from third party data without copying it
smartCopy	Copies a borrowed array or addRefs a non-borrowed array
addRef	Increments the reference count.
deleteRef	Decrements the reference count.
get1	Returns the indexed element from a one-dimensional array
get2	Returns the indexed element from a two-dimensional array
get3	Returns the indexed element from a three-dimensional array
get4	Returns the indexed element from a four-dimensional array
get5	Returns the indexed element from a five-dimensional array
get6	Returns the indexed element from a six-dimensional array
get7	Returns the indexed element from a seven-dimensional array
get	Returns the indexed element from an array of any dimension
set1	Sets the indexed element in a one-dimensional array
set2	Sets the indexed element in a two-dimensional array
set3	Sets the indexed element in a three-dimensional array
set4	Sets the indexed element in a four-dimensional array
set5	Sets the indexed element in a five-dimensional array
set6	Sets the indexed element in a six-dimensional array
set7	Sets the indexed element in a seven-dimensional array
set	Sets the indexed element in an array of any dimension
dimen	Returns the dimension of the array
lower	Returns the lower bound of the specified dimension
upper	Returns the upper bound of the specified dimension
stride	Returns the stride of the specified dimension
length	Returns the length of the Array in the specified dimension
isColumnOrder	Returns true if the array is a dense column-major order array, false otherwise
isRowOrder	Returns true if the array is a dense row-major order array, false otherwise
copy	Copies the contents of source array to dest array
ensure	Returns an array with guaranteed ordering and dimension from any array.
first	Provides direct access to the element data of the array.

---

The functions are listed succinctly in Table 6.3 as well as in detail over the next few pages.

Function: createCol

This method creates a column-major, multi-dimensional array in a contiguous block of memory. dimen should be strictly greater than zero, and lower and upper should have dimen elements. lower[i] must be less than or equal to upper[i]-1 for i ≥ 0 and i < dimen. If this function fails for some reason, it returns NULL. lower[i] specifies the smallest valid index for dimension i, and upper[i] specifies the largest. Note this definition is somewhat un-C like where the upper bound is often one past the end. In SIDL, the size of dimension i is 1 + upper[i] - lower[i].

The function makes copies of the information provided by dimen, lower, and upper, so the caller is not obliged to maintain those values after the function call.

For Fortran, the new array is returned in the last parameter, result. A zero value in result indicates that the operation failed. For Fortran 90/95, you can use the function not_null to verify that result is a valid array.

Function: createRow

This method creates a row-major, multi-dimensional array in a contiguous block of memory. Other than the difference in the ordering of the array elements, this method is identical to createCol.

Function: create1d

This method creates a dense, one-dimensional vector of ints with a lower index of 0 and an upper index of len − 1. This is defined primarily as a convenience for C and C++ programmers; Fortran programmers should note that this subroutine creates arrays whose lower index is 0 not like standard Fortran arrays whose lower index is 1. If len ≤ 0, this routine returns NULL.

Function: create2dCol

This method creates a dense, column-major, two-dimensional array of ints with a lower index of (0, 0) and an upper index of (m − 1, n − 1). If m ≤ 0 or n ≤ 0, this method returns NULL. This is defined primarily as a convenience for C and C++ programmers; Fortran programmers should note that this subroutine creates arrays whose lower index is 0 not like standard Fortran arrays whose lower index is 1.

Function: create2dRow

This method creates a dense, row-major, two-dimensional array of ints with a lower index of (0, 0) and an upper index of (m − 1, n − 1). If m ≤ 0 or n ≤ 0, this method returns NULL. This is defined primarily as a convenience for C and C++ programmers; Fortran programmers should note that this subroutine creates arrays whose lower index is 0 not like standard Fortran arrays whose lower index is 1.

Function: slice

This method will create a sub-array of another array. The resulting array shares data with the original array. The new array can be of the same dimension or potentially less than the original array. If you are removing a dimension, indicate the dimensions to remove by setting numElem[i] to zero for any dimension i that should go away in the new array. The meaning of each argument is covered below.

src

the array to be created will be a subset of this array. If this argument is NULL, NULL will be returned. The returned array borrows data from src, so modifying one array modifies both. In C++, the this pointer takes the place of src.

dimen

this argument must be greater than zero and less than or equal to the dimension of src. An illegal value will cause a NULL return value.

numElem

this specifies how many elements from src should be in the new array in each dimension. A zero entry indicates that the dimension should not appear in the new array. This argument should be an array with an entry for each dimension of src. NULL will be returned for src if either

srcStart[i] + numElem[i] * srcStride[i]	>	upper[i], or
srcStart[i] + numElem[i] * srcStride[i]	<	lower[i]

srcStart

this parameter specifies which element of src will be the first element of the new array. If this argument is NULL, the first element of src will be the first element of the new array. If non-NULL, this argument provides the coordinates of an element of src, so it must have an entry for each dimension of src. NULL will be returned for src if either

srcStart[i] < lower[i], or srcStart[i] > upper[i].

srcStride

this argument lets you specify the stride between elements of src for each dimension. For example with a stride of 2, you could create a sub-array with only the odd or even elements of src. If this argument is NULL, the stride is taken to be one in each dimension. If non-NULL, this argument should be an array with an entry for each dimension of src. The stride values are relative to the original source array, src, so the default stride of one in each dimension is appropriate for cases where you want a dense subsection of the original array.

newLower

this argument is like the lower argument in a create method. It sets the coordinates for the first element in the new array. If this argument is NULL, the values indicated by srcStart will be used. If non-NULL, this should be an array with dimen elements.

Assuming the method is successful and the return value is named newArray, src[srcStart] refers to the same underlying element as newArray[newStart].

If src is not a borrowed array (i. e., it manages its own data), the returned array can manage its by keeping a reference to src. It is not considered a borrowed array for purposes of smartCopy.

Function: borrow

This method creates a proxy SIDL multi-dimensional array using data provided by a third party. In some cases, this routine can be used to avoid making a copy of the array data. dimen, lower, and upper have the same meaning and constraints as in SIDL_double__array_createCol. The firstElement argument should be a pointer to the first element of the array; in this context, the first element is the one whose index is lower.

stride[i] specifies the signed offset from one element in dimension i to the next element in dimension i. For a one dimensional array, the first element has the address firstElement, the second element has the address firstElement + stride[0], the third element has the address firstElement + 2 * stride[0], etc. The algorithm for determining the address of the element in a multi-dimensional array whose index is in array ind[] is as follows:

Note elements of stride need not be positive.

The function makes copies of the information provided by dimen, lower, upper, and stride. The type of firstElement is changed depending on the array value type (see Table 6.2).

Function: smartCopy

This method will copy a borrowed array or increment the reference count of an array that is able to manage its own data. This method is useful when you want to keep a copy of an incoming array. The C++ method operates on this.

Function: addRef

This increments the reference count by one. In C++, this method should be avoided because the C++ wrapper class manages the reference count for you.

Function: deleteRef

This decreases the reference count by one. If this reduces the reference count to zero, the resources associated with the array are reclaimed. In C++, this method should be avoided because the C++ wrapper class manages the reference count for you.

Function: get1

This method returns the element with index i1 for a one dimensional array. The return type of this method is the value type for the SIDL type being held (see Table 6.2). This method must only be called for one dimensional arrays. For objects and interfaces, the client owns the returned reference (i. e., the client is obliged to call deleteRef() when they are done with the reference unless it is NULL). For arrays of strings, the client owns the returned string (i. e., the client is obliged to call free on the returned pointer unless it is NULL). There is no reliable way to determine from the return value cases when i1 is out of bounds.

Function: get2

This method returns the element with indices (i1, i2) for a two dimensional array. The return type of this method is the value type for the SIDL type being held (see Table 6.2. This method must only be called for two dimensional arrays. For objects and interfaces, the client owns the returned reference (i. e., the client is obliged to call deleteRef when they are done with the reference unless it is NULL). For arrays of strings, the client owns the returned string (i. e., the client is obliged to call free on the returned pointer unless it is NULL). There is no reliable way to determine from the return value cases when i1, i2 are out of bounds.

Function: get3

This method returns the element with indices (i1, i2, i3) for a three dimensional array. The return type of this method is the value type for the SIDL type being held (see Table 6.2). This method must only be called for three dimensional arrays. For objects and interfaces, the client owns the returned reference (i. e., the client is obliged to call deleteRef() when they are done with the reference unless it is NULL). For arrays of strings, the client owns the returned string (i. e., the client is obliged to call free() on the returned pointer unless it is NULL). There is no reliable way to determine from the return value cases when i1, i2, i3 are out of bounds.

Function: get4

This method returns the element with indices(i1, i2, i3, i4) for a four dimensional array. The return type of this method is the value type for the SIDL type being held (see Table 6.2). This method must only be called for four dimensional arrays. For objects and interfaces, the client owns the returned reference (i. e., the client is obliged to call deleteRef() when they are done with the reference unless it is NULL). For arrays of strings, the client owns the returned string (i. e., the client is obliged to call free() on the returned pointer unless it is NULL). There is no reliable way to determine from the return value cases when i1, i2, i3, or i4 are out of bounds.

Function: get5-7

Methods get5–get7 are defined in an analogous way.

Function: get

This method returns the element whose index is indices for an array of any dimension. The return type of this method is the value type for the SIDL type being held (see Table 6.2). This method can be called for any positively dimensioned array. For objects and interfaces, the client owns the returned reference (i. e., the client is obliged to call deleteRef() when they are done with the reference unless it is NULL). For arrays of strings, the client owns the returned string (i. e., the client is obliged to call free() on the returned pointer unless it is NULL). There is no reliable way to determine from the return value cases when indices has an element out of bounds.

Function: set1

This method sets the value in index i1 of a one dimensional array to value. The type of the argument value is the value type for the SIDL type being held (see Table 6.2). This method must only be called for one dimensional arrays. For arrays of objects and interfaces, the array will make its own reference by calling addRef() on value, so the client retains its reference to value. For arrays of strings, the array will make a copy of the string, so the client retains ownership of the value pointer.

Function: set2

This method sets the value in index (i1, i2) of a two dimensional array to value. The type of the argument value is the value type for the SIDL type being held (see table  6.2). This method must only be called for two dimensional arrays. For arrays of objects and interfaces, the array will make its own reference by calling addRef() on value, so the client retains its reference to value. For arrays of strings, the array will make a copy of the string, so the client retains ownership of the value pointer.

Function: set3

This method sets the value in index (i1, i2, i3) of a three dimensional array to value. The type of the argument value is the value type for the SIDL type being held (see table  6.2). This method must only be called for three dimensional arrays. For arrays of objects and interfaces, the array will make its own reference by calling addRef() on value, so the client retains its reference to value. For arrays of strings, the array will make a copy of the string, so the client retains ownership of the value pointer.

Function: set4

This method sets the value in index (i1, i2, i3, i4) of a four dimensional array to value. The type of the argument value is the value type for the SIDL type being held (see table  6.2). This method must only be called for four dimensional arrays. For arrays of objects and interfaces, the array will make its own reference by calling addRef() on value, so the client retains its reference to value. For arrays of strings, the array will make a copy of the string, so the client retains ownership of the value pointer.

Function: set5-7

Methods set5–set7 are defined in an analogous way.

Function: set

This method sets the value in index indices for an array of any dimension to value. The type of the argument value is the value type for the SIDL type being held (see table  6.2). For arrays of objects and interfaces, the array will make its own reference by calling addRef() on value, so the client retains its reference to value. For arrays of strings, the array will make a copy of the string, so the client retains ownership of the value pointer.

Function: dimen

This method returns the dimension of the array.

Function: lower

This method returns the lower bound on the index for dimension ind of array.

Function: upper

This method returns the upper bound on the index for dimension ind of array. If the upper bound is greater than or equal to the lower bound, the upper bound is a valid index (i. e., it is not one past the end).

Function: stride

This method returns the stride for a particular dimension. This stride indicates how much to add to a pointer to get for the current element this the particular dimension to the next.

Function: length

This method returns the length for a particular dimension. It is equivalent to the statement upper(dim) - lower(dim) + 1.

There is also a shortcut for one-dimensional arrays available in C++ and Java. In C++, if length is called with no arguments, it defaults to the first dimension. In Java Array1 one-dimensional Java arrays have a length function that takes no arguments.

Function: isColumnOrder

This method returns a true value if and only if array is dense, column-major ordered array. It does not modify the array at all.

Function: isRowOrder

This method returns a true value if and only if array is dense, row-major ordered array. It does not modify the array at all.

Function: copy

This method copies the contents of src to dest. For the copy to take place, both arrays must exist and be of the same dimension. This method will not modify dest’s size, index bounds, or stride; only the array element values of dest may be changed by this function. No part of src is changed by this method.

If dest has different index bounds than src, this method only copies the elements where the two arrays overlap. If dest and src have no indices in common, nothing is copied. For example, if src is a 1-d array with elements 0-5 and dest is a 1-d array with element 2-3, this function will copy element 2 and 3 from src to dest. If dest had elements 4-10, this method could copy elements 4 and 5.

Function: ensure

This method is used to obtain a matrix with a guaranteed ordering and dimension from an array with uncertain properties. If the incoming array has the required ordering and dimension, its reference count is incremented, and it is returned. If it doesn’t, a copy with the correct ordering is created and returned. In either case, the caller knows that the returned matrix (if not NULL) has the desired properties.

This method is used internally to enforce the array ordering constraints in SIDL. Clients can use it in similar ways. However, because the method was intended as an internal Babel feature, is not available in Java or Python.

The ordering parameter should be one of the constants defined in enum sidl_array_ordering (e. g.
sidl_general_order, sidl_column_major_order, or sidl_row_major_order). If you pass in
sidl_general_order, this routine will only check the dimension of the matrix.

Function: first

This method provides direct access to the element data. Using this pointer and the stride information, you can perform your own array accesses without function calls. This method isn’t available for arrays of strings, interface and objects because of memory/reference management issues. There is no equivalent of this function in Java or Python. To see how to get direct array access in Fortran 90/95, see Chapter 11.

The Fortran versions of the method return the lower, upper and stride information in three arrays, each with enough elements to hold an entry for each dimension of array. Because fortran 77 does not have pointers, you must pass in a reference array, array. Upon exit, ref(index) is the first element of the array. The type of ref depends on the type of the array.

WARNING:

While calling the Fortran direct access routines, there is a possibility of an alignment error between your reference pointer, ref, and the pointer to the first element of the array data. The problem is more likely with arrays of double or dcomplex; although, it could occur with any type on some future platform. If index is zero on return, an alignment error occurred. If an alignment error occurs, you may be able to solve it by recompiling your Fortran files with flags to force doubles to be aligned on 8 byte boundaries. For example, the -malign-double flag for g77 forces doubles to be aligned on 64-bit boundaries. An alignment error occurs when (char *)ref minus (char *)sidl_double__array_first(array) is not integer divisible by sizeof(datatype) where ref refers to the address of the reference array.

Here is an example fortran 77 subroutine to output each element of a 1-dimensional array of doubles using the direct access routine. Fortran 90/95 has a pointer in the array derived type when direct access is possible.

For a 2-dimensional array, the loop and array access is

Suppose you are wrapping a legacy Fortran application and you need to pass a SIDL array to a Fortran subroutine. Further suppose there is a fortran 77 and Fortran 90/95 version of the subroutine. For example, the fortran 77 subroutine has a signature such as:

The Fortran 90/95 subroutine has basically the same signature as follows:

Here is one way to wrap this method using SIDL. First of all, the SIDL method definition specifies that the array must be a 1-dimensional, column-major ordered array. This forces the incoming array to be a dense column.

Given that method definition in a class named Class and a package named Pkg, the implementation of the wrapper should look something like the following for fortran 77:

Similarly, it should look something like the following for Fortran 90/95, where the include statements are required at the top of the “Impl” file to ensure proper handling of subroutine names that have automatically been mangled by the Babel compiler:

The C Macro API

Many of the SIDL array access functions have a corresponding C macro API for those who fear the function overhead of the C function API. When efficiency is not a concern, we recommend using the function API, but the C macro API is preferable to the direct access to the data structure. Parts of the macro API are not available for arrays of strings, interfaces or objects because the issues associated with memory and object reference management.

The macro API is very similar to the function API; however, a single set of macros applies to all the supported array types. The macro names are independent of the type of array you’re accessing.

Return the dimension of array.

Return the lower bound on dimension ind.

Return the upper bound on dimension ind.

Return the extent on dimension ind. The extent is equal to sidlUpper(array,ind) - sidlLower(array,ind) + 1.

Return the stride for dimension ind. The stride is the offset between elements in a particular dimension. It can be positive or negative. It is in terms of number of value types (i. e., it’s 1 means contiguous regardless of what data type).

The macros to access array elements of array elements are unavailable for arrays of strings, classes and interfaces.

Provide access to array elements to arrays of dimension 1–7. This macro can appear on the left hand side of an assignment or on the right hand side in an expression. These macros blindly assume that the dimension and indices are correct.

The macros to access the address of array elements are unavailable for arrays of strings, classes, and interfaces.

Return the address of elements in arrays of dimension 1–7. This macro can appear on the left hand side of an assignment or on the right hand side in an expression. These macros blindly assume that the dimension and indices are correct.

The C Data Structure

If even the macro interface is not fast enough for you, you can access the internal data structure for all the basic types except string. You cannot access the internal data structure for arrays of strings, interfaces and objects.

The basic form of the C data structure for type XXXX is:

The string “<value type for XXXX>” should be replaced by something like sidl_boolfor an array of bool, int32_t for any array of int, double for an array of double, int64_t for an array of long, etc. (See Table 6.2)

d_dimen

tells the dimension of the multi-dimensional array. d_lower, d_upper, and d_stride each point to arrays of d_dimen int32_t’s. d_lower[i] provides the lower bound for the index in dimension i, and d_upper[i] provides the upper bound for the index in dimension i. Both the lower and upper bounds are valid index values; the upper bound is not one past the end.

d_borrowed

is true if the array does not managed the data that d_firstElement points too, and it is false otherwise. This mainly influences the behavior of the destructor.

Clients should not modify d_lower, d_upper, d_stride, d_dimen, d_borrowed or (in the case of pointers) the values to which they point.

d_stride[i]

determines how elements are packed in dimension i. A value of 1 means that to get from element j to j+1 in dimension i, you add one to the data pointer. Negative values for d_stride can be used to express a transposed matrix. The definition also allows either column or row major ordering for the data, and it also allows treating a subsection of an array as an array.

The data structure was inspired by the data structure used by Numeric Python; although, in Numeric Python, the stride is in terms of bytes. In SIDL, the stride is in terms of number of objects. One can convert to the Numeric Python view of things by multiplying the stride by the sizeof the value type.

6.5  Interface Contracts

Interface contracts define behaviors expected of callers (or clients) and callees (or servers) of methods. These behaviors are specified within clauses of SIDL interfaces and classes and may be checked at runtime through options used to establish an enforcement policy. Executable interface contracts thereby provide a mechanism for helping ensure software is implemented and used correctly. This section focuses on specification basics and traditional interface contract enforcement options.

Contract Clauses

Contract clauses define constraints on properties of methods (including argument and return values)² and objects. Babel supports three types of clauses using SIDL syntax borrowed from Eiffel []. Those clauses are: preconditions, postconditions, and class invariants.

Each clause corresponds to a different set of enforcement points. Precondition and postcondition clauses are specified on a method basis. A precondition declares constraints on invocation of a method while a postcondition constrains its effects. In some cases, there may be properties needing to hold throughout the life of an instance of a class. Rather than require the assertions be specified in the precondition and postcondition clauses of every method, the class invariant clause, which can also be specified on interfaces, should be used.

The general structure of a SIDL method specification is provided below. The specification defines the method signature; that is, it provides the name, parameter list, return type, and any exceptions thrown (or raised) by the method. The SIDL specification can also include the definition of preconditions in the require clause and postconditions in the ensure clause.

When contract clauses are added to the specification, each method’s throws clause must explicitly list the appropriate contract clause violation exception. The exceptions, as defined in sidl.sidl, are shown below. The need for explicitly declaring the exceptions is based on Babel’s current SIDL-to-C++ exceptions mapping in the generated middleware.

The basic structure of a contract clause, including the clause type (i. e., require, ensure, or invariants), is provided below. Each clause, when present, contains a list of assertions. Each assertion may be preceded by a label. The label serves two purposes. First, if thoughtfully written, it provides a succinct “description” of the purpose of the assertion in the specification. Second, through its automatic inclusion in the exception message of a violated contract, the label helps identify the offended assertion.

For example, the SIDL specification of a vector dot product method with a contract is:

This specification includes both precondition and postcondition clauses. The precondition clause, identified by require, contains six executable assertions. The first five assertions require the two normal SIDL arrays, u and v, be non-null, one-dimensional arrays of the same size. The fifth assertion requires the tolerance argument, tol, be non-negative. The postconditions clause, identified by ensure, contains three assertions. The is pure assertion indicates implementations should be side-effect free³. This allows the method to be included in the contract of another method. The remaining assertions indicate all implementations of the method must ensure the following, assuming the preconditions are satisfied:

1. if u and v are equal then the result of calling vuDot should be non-negative; and
2. if u and v are both zero vectors then the result should be within the provided tolerance.

The tolerance argument, tol, was only added here to support assertions in the postconditions clause. That is, the argument is not expected to be needed or used by any implementation of the method.

It is important to keep in mind that the assertions within interface contracts only need to hold at the method call boundary. The implementations of some methods may have to temporarily violate the contract during processing. However, as long as the corresponding assertions hold at the call boundary, the contract is not actually violated.

Optional interface contracts consist of clauses defining obligations on callers and callees. Clauses, when specified, must contain assertions required to hold at the appropriate point(s) during execution. Assertions within precondition (and invariant) clauses must hold immediately before the method is executed; whereas, postcondition (and invariant) clause assertions must hold immediately after control returns from the method. More information on SIDL specifications, including supported operators and built-in functions, can be found in Chapter 21.

Contract Enforcement

The options used to establish an interface contract enforcement policy should be based on the goals of a particular application run. During testing and debugging, contract enforcement tends to focus on determining whether the caller and callee conform to the specification. Historically, contract enforcement is disabled during deployment. Consequently, traditional interface contract enforcement tends to be all-or-nothing for one or more type of contract clause.

The simplest approach is to always enforce all contract clauses. SIDL provides the setEnforceAll helper method, whose specification is provided below, for setting the associated enforcement options. While this strategy makes testing straightforward, it is important to keep in mind that it carries the risk of not fully testing the compliance of the codes. For example, if the test suite is not sufficiently thorough, there is a risk of not exposing non-compliance of contract clauses in downstream methods when there can be dependencies involving sequences of method calls.

A traditional alternative for test suites singling out callers from callees involves separately enforcing precondition and postcondition clauses. For example, when testing whether one or more implementations of an interface comply with their specification, enforcement is generally limited to postconditions (with test codes satisfying the preconditions). Once confidence is gained in the implementation, the callers may be tested with only precondition enforcement enabled (with test codes violating the preconditions). The full range of clause type-based ContractClass options are provided below. Separating clause enforcement in this manner therefore allows test suites to distinguish between caller and callee contract compliance.

Assertion enforcement has historically been considered to be too time consuming to allow during deployment. So the traditional approach has been to disable their enforcement. SIDL provides the setEnforceNone helper method, whose specification is shown below, for disabling contract enforcement at runtime.

Enforcement policies in affect should be based on the goals of a given execution. Testing and debugging with contracts tend to focus on caller and callee compliance; therefore, enforcement can involve checking all or type-specific subsets of contract clauses. Contract enforcement is traditionally disabled during deployment, however. All of these strategies are supported through two SIDL helper methods. Language-specific examples of the use of these methods are provided in Part II. Additional information, including advanced and experimental enforcement capabilities, can be found in Chapter 21.

6.6  SIDL Runtime

The runtime library supports a collection of interfaces and classes, some of which form the basis of the SIDL object model while, as discussed in other sections of this chapter, others provide enhanced capabilities.

Inheritance

The object model core consists of base interfaces, classes, and exceptions. All interfaces implicitly inherit from sidl.BaseInterface. Classes implicitly inherit from sidl.BaseClass, which implements sidl.BaseInterface. Hence, all objects can be cast to sidl.BaseInterface and sidl.BaseClass. Exceptions must explicitly implement the interfaces in sidl.BaseException. The easiest way to do this is to extend sidl.SIDLException, which the basic Exception functionality, including getNote and setNote. One or more of these functions can also be overriden. If a method in SIDL claims to throw an object that does not inherit from sidl.BaseException, Babel will report it as an error.

Interfaces

The SIDL runtime library supports the six interface categories described below.

Base

The base class, interface, and exception upon which all Babel-enabled software builds.

Contract Enforcement

Contract enforcement policy class and contract clause exceptions used to establish enforcement options and identify, at runtime, contract clause violations, respectively.

Library Handler

The DLL and Loader classes facilitate dynamic loading of objects at runtime.

Introspection

The ClassInfo interface and ClassInfoI class enable checking meta-data associated with a class.

I/O

The input-output package used for serializing and deserializing SIDL types.

RMI

The rmi package used for managing remote method invocations.

The associated capabilities, as defined in sidl.sidl, are:

6.7  Objects

One of the strategies that SIDL uses to enforce language interoperability is to define an object model that it supports across all language bindings. This enables real object-oriented programming in non-OO languages such as C and fortran 77. This also means that the inheritance mechanisms inside real OO languages may be circumvented.

Contrary to newer scripting languages such as Python and Ruby, not everything in SIDL is an object. Only classes (abstract or not) and interfaces are objects. Everything else (e. g. arrays, enums, strings, ints) is something other than an object and therefore outside the scope of this section.

Babel’s Object Model

SIDL defines three types of objects: interfaces, classes, and abstract classes. A SIDL interface is akin to a Java interface or a C++ pure abstract base class. It is an object that defines methods (aka member functions), but carries no implementation of those methods. A class by comparison is always concrete; meaning that there is an implementation for each of its methods and it can be instantiated. An abstract class falls somewhere between an interface and a class. It has at least one method unimplemented, so it cannot be instantiated, but it also may have several methods that are implemented and these implementations can be inherited.

SIDL supports multiple inheritance of interfaces and single inheritance of implementation. This is a strategy found in other OO languages such as Java and ObjectiveC. The words to distinguish these two forms of inheritance are extends and implements. Interfaces can extend multiple interfaces, but they cannot implement anything. Classes can extend at most one other class (abstract or not), but can implement multiple interfaces.

Furthermore, any inherited abstract methods (inherited from either and abstract parent class or and implemented interface) will default to abstract unless they are re-declared in the current class. If a concrete class implements many large interfaces, this can result in a fairly large list of redeclared functions in the class definition. As a shortcut, we included the implements-all directive, a short hand that states explicitly that we intend to implement every method in the named interface concretely. That’s why, in the following example, class B must be declared abstract, but class D is concrete. Class B does not redeclare the printMe function, but class D implements-all. There is no similar directive for inheritance from abstract classes.

We display a small SIDL file below and finish this subsection with a discussion of its details.

object.A is an interface that has two methods display() and print(). Both of these methods take no arguments and return no value. (We will discuss arguments and return values in the next section.) Since object.A is an interface, there is no implementation associated with it, and Babel will not generate any implementation code associated with it.

object.B is an abstract class that inherits from object.A. Since it redeclares the display() method, Babel will generate the appropriate code for an implementation of this method only. It will not generate code for the other inherited method print() (since it wasn’t declared in the SIDL file) and it will not generate constructors/destructors since the class is abstract.

object.C is a concrete class that extends the abstract class object.B it then lists only the unimplemented method print(), implying that it will use the implementation of display() it inherited from its parent.

object.D is also a concrete class that uses the implements-all

directive. This is identical to using implements and then listing all the methods declared in the interface. The implements-all directive was added to SIDL as a convenience construct and to save excessive typing in the SIDL file. By virtue of the implements-all directive, object.D will provide its own implementation of all of object.A’s methods, namely display() and print().

Methods on Objects

Methods in SIDL are virtual by default. This means that the actual binding of a method invocation to an actual implementation is determined at runtime, based on the concrete type of the object.

SIDL currently defines three modifiers to methods that change their default behavior.

• final   :   Final methods are the opposite of virtual. While they may still be inherited by child classes, they cannot be overridden.
• static   :   Static methods are sometimes called “class methods” because they are part of a class, but do not depend on an object instance. In non-OO languages, this means that the typical first argument of an instance is removed. In OO languages, these are mapped directly to an Java or C++ static method.
• local   :   local is a keyword that relates to RMI. A local method cannot be called on a remote object. Any call on a local method must be an in-process call, or a PreViolation will be thrown.
• oneway   :   oneway is a keyword that relates to RMI. A oneway method can only take in arguments, no out arguments. This allows the oneway method to be called with a oneway network message, so the user doesn’t need to wait for a response.
• nonblocking   :   nonblocking is a keyword that relates to RMI. A nonblocking method is split into two methods, method_send() and method_recv(). method_send() takes the in arguments and immediately returns a sidl.rmi.Ticket. This Ticket can be used to determine when the remote method returns, and get the out arguments.

Starting with Babel 0.11.0, all SIDL methods implicitly throw sidl.RuntimeException. A sidl.RuntimeException can be generated by the Babel generated glue code. For example, if the code is making a call across the network using remote method invocation and the network goes down, Babel’s glue code would generate a RuntimeException. In cases where the implementation throws an unexpected exception (i. e., not one that is declared in the method’s SIDL declaration), the glue code can generate a RuntimeException.

Parameter Passing

Each parameter in a method call obeys the following syntax

[ (modifier) ] (mode) (type) (name)

Where (mode) is one of in, out, or inout; (type) is any SIDL recognized type; and (name) is any non-reserved word⁴. The (modifier) is optional, and currently unimplemented. SIDL currently reserves the word copy for future use as an parameter modifier, and may add others in the future⁵.

For new users, the parameter’s mode (e. g. in, out, or inout) is perhaps the most troublesome. On the surface, it’s easy to explain that in parameters are passed into the code, out parameters come out, and inout parameters do both. More specifically the rules are:

1. in does not mean const.
2. in arguments are passed by value, therefore what happens inside the function has no effect on the value passed in (from the perspective of the caller).
3. inout arguments are passed by reference. The callee is allowed to do whatever it wants with the data passed in, and changes made by the callee are sent back to the caller. For interfaces, classes, and normal arrays, the callee can even destroy the reference, create a new object or array, and return a reference to it.
4. Objects, interfaces and arrays should be allocated using the create methods provided. Types created on the stack should never be passed as an inout argument, since the implementation may want to destroy it.
5. out arguments are also passed by reference, but the incoming value is ignore and typically overwritten. Do Not attempt to pass in a value to a function through an out argument. There is no guarantee that the data will make it to the Implementation, and if the data is lost, there is no guarantee the reference will be correctly destroyed.

When an exception is thrown, the value of out parameters is undefined. Thus, the client code should not attempt to free out string values or decrement reference counts for objects or arrays when an exception has been thrown. Some bindings may initialize point types to a NULL value, but the client should not depend on this behavior.

For strings and reference counted objects (i. e., objects, interfaces, and arrays) called a resource here, these rules can be confusing. It is useful to think about who retains ownership of the resource and the phases of method call.

in

The client owns the resource before the call, and the callee borrows the reference. In the case of a string, the client owns the string data, and the implementation would have to copy the string if it wanted to retain a reference. Similarly, the implementation would have to increment the reference count of an object or smart copy an array. In the case of an exception being thrown, the in parameters are unmodified.

inout

The client initially owns the resource before the call, and it transfers its ownership to the callee. Thus, the callee is allowed to decrement the reference count of the object or free a string. When the callee is finished, it transfers ownership back to the caller (or potentially returns a NULL object/string). In the event of an exception, the caller should ignore the outgoing parameter values, and the implementation must insure that the object’s reference counts are decremented and incoming string values are free’ed.

out

The incoming values of out parameters are ignored, and the callee creates any strings or objects that are to be returned. When the callee returns, it transfers ownership of the parameters to the caller. In the event of an exception, the caller must ignore the value of out parameters because they may be uninitialized.

Method Overloading

Method overloading is the object-oriented practice of defining more than one method with the same name in a class. Doing so allows the convenient reuse of a method name when, for example, the underlying implementations differ based on the types of the arguments. Actually, support for overloaded methods typically relies on the signature of each method to ensure uniqueness. In this case, the signature consists of the method name along with the number, types, and ordering of its arguments.

Since Babel supports languages that do not support method overloading, a mechanism for generating unique names was needed. These are typically generated by compilers based on hashing the argument types into the method name. However, developers often manually address this with far fewer characters than would be used by a compiler. Consequently, it was determined it would be more efficient to leave the task of identifying the unique name to the developer. Therefore, Babel allows the specification of the base, or short, method name along with an optional method name extension as illustrated in the SIDL file below for the getValue method.

Thus, the full method name is the concatenation of the short name followed by the name extension. When generating code for supported languages, Babel makes use of either the short or full method name as appropriate for the language(s) involved. For those that support method overloading, such as C++ and Java, Babel relies only on the short method name, thus ignoring the extension. For the rest, like C, Fortran, and Python, Babel must make use of the full name to ensure methods are uniquely identified.

In the example above, the first method specification takes no arguments so has no name extension. This is acceptable because there are no potentially conflicting methods at this point for any programming language supported by Babel. The second method, with the user-defined name extension of Int, takes a single int argument, resulting in the unique method name getValueInt. The last method, with a user-defined name extension of Double, takes a single double argument, resulting in the unique method name of getValueDouble. Examples of calling overloaded methods from Babel-supported languages can be found in the respective language binding chapters.

6.8  XML Repositories

Even though SIDL is currently the primary input format for Babel, it is not the only format Babel understands. For type repositories (similar in function to include directories for C/C++ headers) the preferred language to articulate types is XML.

Babel has the capabilities to convert SIDL files into XML files adhering to the sidl.dtd. This capability is explained further in Chapter 16. The XML files in these repositories can be included in subsequent runs quickly since all the external references were resolved by Babel during their creation. A SIDL file may refer to unresolved types.

1

meaning non-strided

2

Contract clauses should never replace defensive programming data checks since clause enforcement may be disabled during deployment. The data checks of defensive programming, on the other hand, should be executed on every run since they are needed to protect against serious, undesirable side-effects that include abrupt, unexplained termination.

3

The is pure assertion is a non-executable annotation since Babel is not equiped to statically analyze source code for any of the supported programming languages.

4

Refer to Section A.2 for the list of reserved words

5

Babel is still pre-1.0 after all!

Chapter 7  Upgrade Notes

7.1  Upgrading from Babel 1.0 to 1.4

This section covers some of the important changes for users upgrading from Babel 1.0 to Babel 1.4. Users who are new to Babel 1.4 should skip this chapter because it gets into details that only experienced Babel users will understand.

There are two major changes for users upgrading. The first involves renaming certain splicer blocks in the C and C++ bindings, and the second involves the extra comments needed for the CCA’s Bocca IDE. Both these changes require new command line options.

Some splicer blocks have been renamed from what they were in Babel 1.0. The _misc and _includes in a C or C++ implementation header file have been renamed to _hmisc and _hincludes. The goal of this change has to give each splicer block a unique name across the implementation header and implementation source files. In Babel 1.0, the header and source both have a splicer blocks named _misc and _includes. This made things confusing for Bocca users.

To help users upgrading from Babel 1.0 to 1.4, Babel 1.4 has a --rename-splicers command line option that will automatically rename the header splicer blocks whose names have changed. Once you’ve generated new implementation header files, you do not need to keep using --rename-splicers.

To support CCA’s Bocca, Babel 1.0 introduced extra comments to guide the Bocca IDE to blocks of text that need to be edited. In Babel 1.4, you need to specifically request these extra comments with --cca-mode.

Chapter 8  C Bindings

8.1  Introduction

This chapter gives an overview of the C bindings for SIDL. Common aspects of the bindings, such as the mapping of SIDL data types to their C representatives, are presented in Section 8.2. Issues of concern to callers written in C are addressed in the client-side bindings discussion in Section 8.3, while callees written in C would benefit from a review of implementation-side issues in Section 8.4. Although it would defeat the multilingual interoperability goals of Babel, programs can be written solely with a C compiler since Babel’s Intermediate Object Representation (IOR) and all objects in the sidl name space (e. g. sidl.BaseClass, etc.) are implemented in C.

8.2  Basics

As with any programming language-neutral technology, translations must be made between abstract constructs supported by the technology and the corresponding concrete constructs in the native programming language. Due to the need to identify types in a global context, Subsection 8.2.1 describes the convention used to establish name spaces. Conventions for generating language-specific method signatures are given in Subsection 8.2.2. The mapping of SIDL fundamental types is given in Subsection 8.2.3. Finally, the process of casting between different types is described in Subsection 8.2.4.

8.2.1  Name space

Since C does not have built-in mechanisms for protecting the global name space, generated bindings avoid name space collisions by using struct and method names that incorporate all relevant naming information. Without this approach, there would be multiple structures or routines with the same name. For a type Z in package X.Y, for example, the name of the type that C clients use for an object reference is X_Y_Z. The name is defined as follows in the X_Y_Z.h header file:

Method names, as discussed in Subsection 8.2.2, are built in a similar manner.

8.2.2  Method signatures

The name of a C routine used to call a SIDL method is a concatenation of the package, class (or interface), and method name, with period characters replaced with underscores. If the method is specified as overloaded (i. e., has a name extension), the extension is appended. 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. With the addition of remote method invocation (RMI) support, all methods now implicitly throw exceptions. Hence, an extra out parameter for the exception is added as the last parameter of the signature.

The following SIDL method — taken from the Babel regression tests — is an example of a method that can throw multiple exception types:

The corresponding C API is:

Note the addition of the object pointer (i. e., self) and exception (i. e., _ex) parameters.

8.2.3  Data types

---

Table 8.1: SIDL to C Type Mappings

SIDL TYPE	C TYPE
int	int32_t
long	int64_t
float	float
double	double
bool	typedef sidl_bool
char	char
string	char *
fcomplex	struct sidl_fcomplex
dcomplex	struct sidl_dcomplex
enum	enum
opaque	void *
interface	typedef
class	typedef
array	struct *

---

Basic SIDL types are mapped into C according to Table 8.1. The remainder of this subsection illustrates use of enumerations and arrays.

Enumerations

Since SIDL enumerations map to C enumerations, their use is fairly straight-forward. The appropriate header file must be included. The naming convention for enumerations is enums followed by the specified enumeration type and enumeration value name, where an underscore is used to separate each part. For example, a variable can be assigned the blue constant for the color enumeration of the sample in Subsection 6.3 as follows:

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 discusses both within the context of C bindings. More information on the C version of the SIDL array API can be found in Subsection 6.4.

In addition to defining the object structure and associated type for user-defined interfaces and classes, Babel also defines a corresponding array structure for normal SIDL arrays. The C mappings for the SIDL base interface and class are:

Given the package num and class Linsol with the solve method specified in Subsection 6.4, the corresponding generated C API is:

In this example, data for each array is passed as a double pointer with the index parameters being normal in integers. The one catch for C programmers is that A is in column-major order — not the typical row-major ordering used in C.

Access to the element in row i and column j can be facilitated using RarrayElem2(A,i,j,m). RarrayElem2, defined in sidlArray.h, is a convenience macro — for C and C++ programmers — supplied to facilitate accessing r-arrays in column-major order. Access to memory by stride one involves making the first index argument to RarrayElem2, i, the inner loop. Since valid pointers are always required for raw arrays, passing NULL for A, x, or b is not allowed.

8.2.4  Type casting

C bindings for interfaces and classes include two implicitly defined methods for performing type casts. The methods are: _cast and _cast2. The _cast method casts a SIDL interface or object pointer to a sidl.BaseClass pointer. The _cast2 method casts a SIDL interface or object pointer to a named type pointer. In the latter case, the client is responsible for casting the return value into the proper pointer type. Using sidl.BaseClass as an example, signatures of the two methods are:

Using either method results in the reference count of the underlying object being increased if the cast succeeded. Success can be determined by checking the return value for a non-NULL result. That is, if a NULL value is returned from either method, then the cast failed or obj was NULL.

NOTE: These methods did not increment the reference count in Babel releases prior to 0.11.0.

8.3  Client-side

This section summarizes aspects of generating and using the C bindings associated with software wrapped with Babel’s language interoperability middleware. The bindings generation process is presented before the conventions used to name C header files are described. 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.

8.3.1  Bindings generation

C stubs (i. e. code to support C clients for a set of SIDL-specified classes or interfaces), are created by invoking Babel as follows¹:

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

or more cryptically

% babel -E -cC file.sidl

Using the --exclude-external flag avoids generation of files for symbols referenced (but not specified) in file.sidl; thereby, reducing the total number of generated files. Of the files generated, those ending in _IOR.h and _IOR.c contain the Intermediate Object Representation (IOR). Files ending with _Stub.c are the C stubs — the interface between C clients and the IOR. The remaining header files contain the C client API.

To use the bindings, you must compile and link the stub files against the SIDL runtime library and an implementation of the API.

8.3.2  Header files

The hierarchical nature of SIDL packages lends itself to multiple options for including enumerations, interfaces, and classes. The naming convention for associated header files uses underscore-separated parts corresponding to the package hierarchy. That is, type X.Y.Z — where X is the name of the package, Y the subpackage, and Z the class — is included with #include "X_Y_Z.h". The header files for the whole subpackage, X.Y, are included with #include "X_Y.h". For instance, all types in the sidl name space are included in #include "sidl.h".

Babel ensures each generated client-side header file automatically includes sidl_header.h, which defines:

1. struct sidl_dcomplex for the SIDL dcomplex type with parts named real and imaginary;
2. struct sidl_fcomplex for the SIDL fcomplex type with parts named real and imaginary;
3. int32_t and int64_t for the SIDL int and long types;
4. a typedef for sidl_bool for the SIDL bool type;
5. preprocessor symbols TRUE and FALSE; and
6. function prototypes for the multi-dimensional array APIs for the basic SIDL types.

8.3.3  Object management

SIDL-specified objects are managed through explicit creation and reference counting. An additional implicit method, called _create, must be invoked to create new instances of a concrete class. The _create method returns a new reference that must be managed by the client. The following is an example of its signature:

References are then managed through methods inherited from sidl.BaseInterface. The methods are addRef and deleteRef, where addRef is used to increment the reference counter while deleteRef decrements it and, if the count reaches zero, frees any associated memory — assuming the developer properly implemented the destructor. Their C APIs for sidl.BaseInterface are:

These same methods can be called from the sidl.BaseClass bindings. In fact, since all SIDL-specified interfaces inherit from sidl.BaseInterface and all classes from sidl.BaseClass, every C binding for an interface or class will inherit addRef and deleteRef methods. Their C APIs for sidl.BaseClass are:

8.3.4  Static methods

Static methods are class-wide so not associated with an object. As a result, self is not automatically added as the first argument to the method signature in the bindings.

8.3.5  Overloaded methods

Using the overload_sample.sidl file from Section 6.7 as an example, recall that three versions of the getValue method are specified. The first signature takes no arguments, the second takes an integer, and the third a boolean. The code snippet below illustrates object creation, method invocation for each of the overloaded methods, and exception handling.

SIDL_CHECK is used to check if an exception has been thrown. If so, control jumps to the code after the EXIT label, which is not illustrated here but is in the example presented in Subsection 8.3.6.

8.3.6  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 and consistency, the argument is of type sidl.BaseInterface. When the exception parameter value is not NULL, an exception has been thrown. In that case, the caller should ignore the value of the other out parameters as well as any return value.

To facilitate exception management, sidl_Exception.h provides several helper utilities. Chief among them are: SIDL_CHECK, SIDL_CATCH, and SIDL_CLEAR. Their use follows from their names. Their signatures are:

EX_VAR (or ex_var) is the exception object itself and sidl_NAME is the string name of the exception type expected to be caught.

The following example, based on the getFib method from Subsection 8.2.2, illustrates not only catching an exception but determining whether it is one of the types identified in the specification:

As an alternative to using SIDL_CHECK, _ex can be compared to NULL directly. Similarly, instead of using SIDL_CATCH, type casting can be used to determine which of the potential exception types was actually thrown.

8.3.7  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, the processes for enabling and disabling execution of the implementation-specific hooks are:

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 8.4.5.

8.3.8  Contract enforcement

Interface contracts specify the expected behaviors of callers (or clients) and callees (or servers) of methods defined for interfaces and classes. Once specified, contracts are optionally enforced at runtime, through checks automatically integrated into the middleware generated by the Babel compiler. This section provides an example of a specification and code snippets for performing basic, traditional contract enforcement — introduced in Section 6.5 — in a C 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 C client using 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 C 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 C 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.

8.4  Implementation-side

This section summarizes aspects of generating and wrapping software written in C. The bindings generation and basic implementation processes are presented first. Since access to private data requires special steps in C, 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.

8.4.1  Bindings generation

To create the C implementation bindings for a set of SIDL classes, Babel should be invoked as follows:

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

or use the short form

% babel -E -sC file.sidl

The command creates a number of files. Specifically, a Makefile fragment, called babel.make, headers, and source files are generated. The only files needing hand-editing are the C “Impl” files — which are header and source files whose names end in _Impl.h or _Impl.c, respectively. More on this in Subsection 8.4.2.

8.4.2  Bindings implementation

Implementation details must be added to the “Impl” files generated in Subsection 8.4.1. Changes to these files must be made between code splicer pairs to ensure their retention in subsequent invocations of Babel. The following is an example of a code splicer pair in C:

A snippet from the Babel-generated implementation file for the solve example from Subsection 6.4 is given below, wherein r-array data are presented as double pointers, and index variables are normal integers.

Data for the 2-D array, A, is in column-major order. The RarrayElem2 helper macro, described in Subsection 8.2.3, can be used to access A.

8.4.3  Private data

Any variables declared in the implementation source file will, by virtue of Babel’s encapsulation, be private. The data can be global to the class — as in static variables declared within the _includes splicer block at the top of the class’s _Impl.c file — or local to an instance — as in variables declared through the private data structure automatically generated in the class’s _Impl.h file. In the former case, special initialization procedures can be added to the built-in _load() method that is guaranteed to be called exactly once per class — before any user-defined methods can even be invoked. The latter case relies on the class-specific data structure automatically generated in the implementation’s header file. As illustrated in the foo.bar example below, the implementer is free to define suitable contents.

Upon instantiation, the object’s data structure is automatically initialized to NULL before the built-in _ctor() method is invoked. Initialization of private data first requires sufficient memory be allocated, as follows:

To avoid leaking memory, allocated private data must be released during instance destruction. This is accomplished through the built-in _dtor() method. Continuing with the foo.bar example, the memory is freed as follows:

Notice all memory locations are initialized to zero before being freed and the internal data pointer set to NULL. These practices are recommended.

Hence, Babel supports the declaration and maintenance of private data on class and instance basis.

8.4.4  Exception throwing

In addition to the helpers discussed in Subsection 8.3.6, sidl_Exception.h provides the following SIDL_THROW macro for throwing exceptions:

The first argument to the macro is the exception output parameter; the second is the type of exception being thrown; and the third provides a textual description of the exception. The following code snippet, which is an extension of the Subsection 8.3.6 example, illustrates the process of using the macro to throw an exception:

EX_VAR is the exception object itself; EX_CLS is the string containing the name of the desired SIDL exception type; and MSG is the string containing the message to be included with the exception. As with the other helpers, the presence of the EXIT label is assumed in the macro. Statements following EXIT should be used to conduct clean up operations, such as deleting any references that were to be returned to the caller.

A good practice we recommend is to set all inout and out array, interface or class pointers to NULL. This makes things work out better for clients who forget to check if an exception occurred or willfully choose to ignore it.

8.4.5  Hooks implementation

As discussed in Subsection 8.3.7, 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 8.3.7, 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.

Chapter 9  C++ Bindings

9.1  Introduction

This chapter gives an overview of the C++ bindings for SIDL as of Babel 1.0. The original C++ bindings, available in the first public release (0.5.0 in July 2001), underwent a significant redesign thanks to Steve Parker at the University of Utah. The result became known as the Utah C++ (i. e., initially tagged UCxx) alternative to the original bindings (0.10.0 January 2005). As of 1.0.0, the Utah version is the only binding released for C++.

Common aspects of those bindings, such as the mapping of SIDL data types to their C++ counterparts, are presented in Section 9.2. Issues of concern to callers written in C++ are addressed in the client-side discussion in Section 9.3, while issues for callees appear in the implementation-side discussion in Section 9.4.

9.2  Basics

This section summarizes basic features that are common to both client and implementation bindings. Subsection 9.2.1 describes conventions used to establish name spaces, while those associated with the generation of subroutines from methods are given in Subsection 9.2.2. The mapping of fundamental and key SIDL types is given in Subsection 9.2.3. Finally, casting between different types is discussed in Subsection 9.2.4.

9.2.1  Name space

The C++ bindings take advantage of language features to protect the global name space. In particular, SIDL packages are mapped to C++ name spaces. Interfaces and classes are mapped to proxy classes, called “stubs”, which serve as the firewall between the application in C++ and Babel’s internal workings. Static SIDL methods are translated into static C++ member functions, while non-static methods are mapped to non-static C++ member functions.

NOTE: For backward compatibility, as of the 1.0 release, the SIDL_USE_UCXX, UCXX, and UCXX_LOCAL preprocessor macros are undefined. SIDL_USE_UCXX is used in #ifdef SIDL_USE_CXX/#endif blocks to specify the ucxx name space. Hence, UCXX was to be used where ::ucxx would normally appear and UCXX_LOCAL where ucxx:: would appear.

9.2.2  Method signatures

Since the bindings are able to map well into C++ language constructs, C++ method signatures correspond very closely to those in the specification. Adapted from the Babel regression tests, the following is an example of a package called ExceptionTest that has a class named Fib with a method, getFib, declared in SIDL as follows:

The corresponding C++ method signature is:

9.2.3  Data types

---

Table 9.1: SIDL to C++ Type Mappings

SIDL TYPE	C++ TYPE
int	int32_t
long	int64_t
float	float
double	double
bool	bool
char	char
string	std::string
fcomplex	sidl::fcomplex
dcomplex	sidl::dcomplex
enum	enum
opaque	sidl::opaque
interface	class
class	class
array	sidl::array (template specialization)

---

Basic SIDL types are mapped into C++ according to Table 9.1. The remainder of this subsection illustrates the use of enumerations and arrays.

Enumerations

Since SIDL enumerations map to C++ enumerations, their use is fairly straight-forward. The appropriate header file must be included. The naming convention for enumerations is for enums to be the name space followed by the specified enumeration type as the name of the enumeration. A given enumeration value name starts with the enumeration type and the name of the constant, with an underscore as the separator. For example, a variable can be assigned the blue constant for the color enumeration of the sample in Subsection 6.3 as follows:

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. This subsection discusses both within the context of C++ bindings.

Although it is feasible to expose the underlying C array API to create, destroy and access normal array elements and meta-data, the C++ bindings provide a sidl::array<T> template mechanism that is more in keeping with C++ idioms. For SIDL built-in types, template specializations of sidl::array<T> are defined in sidl_ucxx.hxx. The array template is specialized in the corresponding stub header for SIDL interfaces and classes. The extensive use of template specialization is used in an effort to hide details that the array implementation shifts between the C++ type externally, and the C-based types stored in the IOR. (See basearray in sidl_ucxx.hxx for the traits classes and grungy implementation details.) For example, the process to create a one-dimensional SIDL array of prime numbers is:

Of course, the example above is only one way to create an array. The list of member functions for all C++ array classes is:

where cxx_array_t, cxx_item_t, ior_array_t, ior_item_t, ior_item_internal_t, iterator,
const_iterator, pointer, and value_type are all public typedefs in the array class. Table 6.3 provides a brief description of each function in the array API.

The values of these typedefs are determined by traits classes, which are a fairly standard, albeit advanced, C++ templating idiom. Refer to any advanced C++ text for a detailed explanation. Both the array_traits<> and array<> template specializations for int32_t are reproduced below. More built-in types and the UCxx stubs for user-defined types can be found in sidl_ucxx.hxx.

The C++ mapping for r-arrays is essentially identical to the mapping for C (see Section 8.2.3). The only difference is that the C++ client header provides an overloaded version of each method containing an r-array taking normal SIDL arrays instead of raw data. For example, the solve method from Section 6.4 produces the following code in the header file.

Multi-dimensional arrays, such as A in the above example, are stored in column-major order. Babel provides macros to access r-array data correctly. In this case, for example, RarrayElem2(A, i, j, m) can be used to access the element in row i and column j. In addition, memory can be accessed by stride one by making the row index the inner loop and the column index the outer. Similar macros are available in sidlArray.h for arrays of dimension 1 through 7.

9.2.4  Type casting

There are two forms of type casting: upcasting and downcasting. Upcasting involves casting from a derived, or subclass, to a more general base class. As a result, it is safely handled with simple assignment. Downcasting works in the other direction; that is, it involves casting an instance of a base class to a more specific subclass. It should be done with sidl::babel_cast<>(). Downcasts are successful if the resulting pointer is non-NULL. This can be checked by a call using either _is_nil() — for determining cast failure — or _not_nil() — for success.

NOTE: Never use dynamic_cast<>() on a SIDL object since Babel’s runtime system needs to be involved in verifying the legality of the downcast.

9.3  Client-side

This section summarizes aspects of generating and using the C++ bindings associated with software wrapped with Babel’s language interoperability middleware. The bindings generation process is presented before the convention used to name C++ header files is described. 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.

9.3.1  Bindings generation

To create the C++ stubs from a SIDL file, invoke Babel as follows¹:

% babel --exclude-external --client=C++ file.sidl

or simply

% babel -E -cC++ file.sidl

This will create a babel.make file, some C headers and sources, and many C++ headers and sources. Files ending in “.c” or “.h” are in C, files ending in “.cxx” or “.hxx” are the C++ binding. The files will need to be compiled and linked together to use the C++ stubs.

There is one command line option particular to this language binding. Using the option --cxx-ior-exception (or it’s short form -x) will generate C++ Babel stubs that check for a null IOR whenever a method is called on them. If a method is called on a stub holding a null IOR, it will throw a NullIORException. If this option is not passed to Babel, the program will simply crash, as C++ would do normally with a null pointer.

9.3.2  Header files

All C++ code generated by Babel #include’s a file called "sidl_ucxx.hh". This file includes babel_config.h, the C header file that defines configuration information. Finally, sidl_ucxx.hh defines some C++ classes in the SIDL name space, such as:

• UCXX ::sidl::StubBase [implementation detail] Common base class for all C++ stubs (proxy classes).
• template<T,U,V> UCXX ::sidl::basearray [implementation detail] Common base class for all C++ array classes.
• typedefs for UCXX ::sidl::fcomplex, UCXX ::sidl::dcomplex, and UCXX ::sidl::opaque (usually std::complex, std::complex and void*, respectively).
• template<T> UCXX ::sidl::array Template array type for SIDL arrays.
• template specializations [implementation detail] specialization of arrays of all SIDL types are defined in this file.

NOTE: C++ headers have a ".hh" or a “.hxx” suffix to distinguish them from C header files. In pre-Babel 0.11, all C++ bindings used the “.hh” suffix. Since Babel 0.11, the “.hh” suffix was exclusively for the original, deprecated binding, while “.hxx” was introduced for the current, UCxx binding.

9.3.3  Object management

SIDL-specified objects are managed through explicit creation with explicit reference counting basically unnecessary. Babel automatically generates a static method called _create that must be invoked to instantiate a concrete class. The default constructor creates the equivalent of a NULL pointer. Below is an example, using standard Babel classes, that creates an object of the base class then upcasts it to its parent interface.

SIDL C++ stubs can be treated as smart-pointers. Constructors, destructors, and operators are overloaded making explicit calls to addRef() or deleteRef() rarely needed.

9.3.4  Static methods

As one would expect, proxy (or “stub”) classes maintain minimal state so that, unlike C or fortran 77, there is no special context argument added to non-static member functions. An example call to the static addSearchPath method of the sidl.Loader class is:

Note the function is invoked directly, through the use of its class name, rather than through an instance.

9.3.5  Overloaded methods

Since C++ is an object-oriented language, the language is much more amenable to the SIDL programming model and less demanding of the programmer than bindings to non-OO languages, such as C and fortran 77.

The basic process of invoking overloaded methods is illustrated below 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 an integer, and the third a boolean.

9.3.6  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. Using the example shown in Subsection 9.2.2, a C++ code fragment (from the regression tests) that utilizes the getFib method is:

Note that SIDL exceptions map well into C++ exceptions allowing native exception mechanisms to be employed.

9.3.7  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, the processes for enabling and disabling execution of the implementation-specific hooks are:

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 9.4.5.

9.3.8  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 C++ 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 C++ 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 C++ 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 C++ 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.

9.4  Implementation-side

This section summarizes aspects of generating and wrapping software written in C++. The bindings generation and basic implementation processes are presented first. Accessing private data is then discussed before illustrating the process of throwing exceptions. Finally, the results of generating implementations with pre- and post-method “hooks” are illustrated.

9.4.1  Bindings generation

Much of the information for generating client-side bindings is pertinent to implementing a SIDL class in C++. SIDL type mappings are listed in Table 9.1. An implementation can call other SIDL methods, in which case the rules for client calls must be followed.

To create the implementation, a valid SIDL file must be generated by invoking Babel as follows:

% babel --exclude-external --server=C++ file.sidl

or simply

% babel -E -sC++ file.sidl

As a result, a makefile fragment called babel.make, several C header and source files, and numerous C++ header and source files are created. The only files that need to be hand-edited are the C++ “Impl” files (i. e., header and source files that end in _Impl.hxx or _Impl.cxx). More on this in Subsection 9.4.2.

9.4.2  Bindings implementation

Implementation details must be added to the “Impl” files generated in Subsection 9.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 a code splicer pair in C++. The actual implementation needs to replace the “// Insert code here...” line.

It is important to understand where and why splicer blocks occur. Splicer blocks appear at the beginning and end of each “Impl” header and source file to allow developers to add #include’s and other miscellaneous items, respectively. In the headers, there is a splicer block that allows a user to make the “Impl” class inherit from some other class. From SIDL’s point of view this is private inheritance — meaning that it is useful for inheriting implementation details — since they cannot be automatically exposed to the SIDL method dispatch mechanism. There is a splicer block inside the class definition for developers to add any desired data members. In the source files, splicer blocks appear in each method implementation. Examples of filling in these splicer blocks are provided in the subsections to follow.

9.4.3  Private data

Any variables declared in the implementation source file will, by virtue of Babel’s encapsulation, be private. The data can be global to the class — as in static variables declared within the _includes splicer block at the top of the class’s _Impl.cxx file — or “local” to an instance. In the former case, special initialization procedures can be added to the built-in _load() method that is guaranteed to be called exactly once per class — before any user-defined methods can even be invoked. The latter case relies on the class-specific name space automatically generated in the implementation’s header file. As illustrated in the foo.bar example below, the implementor is free to define suitable contents.

If the object has no state, these functions are typically empty. The built-in _ctor() method is invoked upon instantiation. Hence, private data should be initialized in the method. For example:

To avoid leaking memory, private data must be released during instance destruction. This is accomplished through the built-in _dtor() method. The memory is then freed as follows:

Hence, Babel supports the declaration and maintenance of private data on class and instance basis.

9.4.4  Exception throwing

The example below shows the standard way to throw an exception in C++. Use of setNote and add methods is not strictly required; however, they do provide information that may be helpful in debugging or error reporting.

9.4.5  Hooks implementation

As discussed in Subsection 9.3.7, 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 9.3.7, 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.

Chapter 10  FORTRAN 77 Bindings

10.1  Introduction

This chapter provides an overview of the fortran 77 bindings for SIDL. Common aspects of the bindings, such as the mapping of SIDL data types to their native fortran 77 representatives, are presented in Section 10.2. Issues of concern to fortran 77 callers are addressed in the client-side bindings discussion in Section 10.3, while fortran 77 callees would benefit from a review of implementation-side issues in Section 10.4.

10.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 10.2.1, while those associated with the generation of subroutines from methods are given in Subsection 10.2.2. Translations between SIDL and native fortran 77 constructs are described in Subsection 10.2.3. Finally, the process of casting between different types is illustrated in Subsection 10.2.4.

10.2.1  Name space

As with C bindings, the language does not have built-in mechanisms for protecting the global name space. As a result, fortran 77 bindings also attempt to avoid collisions by incorporating relevant naming information from the package and class. Since interfaces and classes map to INTEGER*8, there are no naming issues associated with these SIDL types. However, as discussed in Subsection 10.2.2, name space issues do arise for methods.

10.2.2  Method signatures

All SIDL methods are implemented as fortran 77 subroutines regardless of whether they have return values. The name of a subroutine used to call a SIDL method is a concatenation of the package, class (or interface), and method name, where each part is separated by an underscore. If the method is specified as overloaded (i. e., has a name extension), the extension is appended to the name part. An additional string is appended to further distinguish between client-side methods (to be invoked) and the implementation-side, where the former end in “_f” while the latter end in “_fi”.

As for arguments, 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 variable to hold the return value should be passed as an argument following 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 at the end of the signature.

The following SIDL method — taken from regression tests — is an example of a method that can throw multiple exception types:

The corresponding fortran 77 API is:

Note the addition of the object (i. e., self), return (i. e., retval), and exception (i. e., exception) parameters.

10.2.3  Data types

---

Table 10.1: SIDL to fortran 77 Type Mappings

SIDL TYPE	fortran 77 TYPE
int	INTEGER*4
long	INTEGER*8
float	REAL
double	DOUBLE PRECISION
bool	LOGICAL
char	CHARACTER*1
string	CHARACTER*(*)
fcomplex	COMPLEX
dcomplex	DOUBLE COMPLEX
enum	INTEGER
opaque	INTEGER*8
interface	INTEGER*8
class	INTEGER*8
array	INTEGER*8

---

Basic SIDL types are mapped into fortran 77 according to Table 10.1. The remainder of this subsection elaborates on mappings of strings, pointers, enumerations, and arrays.

Strings

When mapping the SIDL string type into fortran 77, some capability was sacrificed to make it possible to use normal looking fortran 77 string handling. One difference is that all fortran 77 strings have a limited fixed size. Specifically, out string parameters are automatically limited to 512 characters each.

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

Pointers

Pointer types, such as opaque, interface, class, and array, translate into 64-bit integers to enable fortran 77 code 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.

Generally, clients should treat opaque, interface, class, and array values as black boxes. However, there is one value that is special. A value of zero for any of these quantities indicates the pointer does not refer to an object, thus making zero the fortran 77 equivalent of NULL. Any nonzero value is or should be a valid object reference. Developers should initialize values to be passed as in or inout parameters to zero or a valid object reference.

Enumerations

SIDL enumerations map to integer values. For compilers that support some form of inclusion, constants are defined in an inclusion file. Specifically, Babel will generate fortran 77 include files in the style of DEC FORTRAN (Compaq FORTRAN? (now HP FORTRAN???)) %INCLUDE. These files are named by taking the fully qualified name of the enum, changing the periods to underscores, and appending .inc.

Given the specification of a car enumeration type from Section 6.3, the corresponding include file is:

The following snippet illustrates the inclusion of the file and an assignment of the mercedes constant:

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 discusses both within the context of fortran 77 bindings. More information on the FORTRAN 77 version of the SIDL array API can be found in Subsection 6.4.

The difference in how normal SIDL arrays and r-arrays are accessed is profound. A normal SIDL array is passed as an integer*8, and accessed using an API or by converting the array data to an index into a known array. R-arrays appear like normal fortran 77 arrays, so there is a big incentive to use r-arrays for performance purposes, when appropriate.

The client-side interface for the solve example introduced in Section 6.4 behaves as if it is a fortran 77 function with the following declarations: