Chapter 20  Creating Objects with Pre-Initialized State

• Introduction to the Backdoor Initializer
• Motivation
• Example
• The Backdoor Initializer in C
• The Backdoor Initializer in fortran 77
• The Backdoor Initializer in Fortran 90/95
• The Backdoor Initializer in C++
• The Backdoor Initializer in Java
• The Backdoor Initializer in Python

20.1  Introduction to the Backdoor Initializer

Internally, every Babel object holds an implementation language specific pointer to the object’s private state data. If the object is implemented in C, the pointer points to a struct named struct package_Class__data. In Java, the private data pointer points to a Java object of the implementation type, Class_Impl, which calls are made on, and which actually holds the object state. The type of the private data is entirely implementation language dependent. The data is usually created or set by the Babel objects user-implemented constructor.

With the Backdoor Initializer, Babel allows a Babel user to set this private data pointer at construction with pre-initialized state. Of course, this is very dangerous. This can only be done if the client language creating the Babel object is the same as the language the object is implemented in, and if the pre-initialized state is of the correct type. If either of these constraints is unsatisfied, the behavior of the backdoor initializer in undefined.

Object construction is a very language specific problem, and therefore this Babel feature is exposed differently in each language. However, in every language, there is some way provided for the class implementor to determine in the constructor code whether the object is being constructed normally, or if the user provided pre-initialized state. In most languages there is a second constructor provided, only in Python is an argument used to determine if the user provided pre-initialized state or not. Most class implementers will not need to do anything with the new constructor. In the case of Backdoor Initialization, usually the right thing to do in a constructor is to do nothing, since the object state was preinitialized by the client. The constructor only needs to be used if the state of the object cannot fully be represented by its private data. For example, an object that opens a TCP/IP connection during construction would almost certainly need that code in the backdoor constructor as well.

20.2  Motivation

The Backdoor Initializer is not a feature that most Babel users will need. However, there are certain cases where the Backdoor Initializer is absolutely required. The most obvious usage case is for wrapping up native objects in a Babelized interface. The allows the implementation language to access the data directly, but other languages must use the provided Babel interface. It was exactly this usage case that inspired the creation of the Backdoor Initializer.

A customer needed to use a Java visualization program to view a graph generated by a C++ library. The customer did not want to modify the Java program significantly. Instead, he created the graph data structure used by the visualizer in Java, and wrapped it in a Babel interface. He was then able to pass the Babelized object to the C++ library, which made calls on the Babel interface to add nodes and edges to the graph. When the C++ library finished, the Java visualizer was able to use the graph as if it was created natively in Java. The visualizer code did not have to be modified in any way to use the graph!

20.3  Example

In this chapter we will use a single example for all Babel supported languages. This example is taken from the wrapper regression test. In this test, there are two sidl classes, wrapper.Data and wrapper.User.

wrapper.Data wraps up some native data, which will be modified by the wrapper.User.accept() call. In this case, the data is just a string and an integer. In order to show the new constructor functionality, we set string called d_ctortest to “ctor was run” in the new constructor.

To reiterate, the client program creates and wraps language specific data in a wrapper.Data babel object. The alternate constructor code is run, which sets the d_ctortest string. The object is then passed to wrapper.User.accept(), which sets the data. The client program can then directly access the data and read what was set by User.accept().

20.4  The Backdoor Initializer in C

In C, the Backdoor Initializer is used through a new _create like static method, _wrapObj. _wrapObj takes a pointer to the private data to be wrapped (a simple struct defined in wrapper_Data__Impl.h).

from wrapper_Data_Impl.h:

From wrapper_Data_Impl.c; notice the new constructor ctor2, which is only called with backdoor initialization.

from the client program wraptest.c: (Note that we must include wrapper_Data_Impl.h)

20.5  The Backdoor Initializer in fortran 77

In fortran 77, using the Backdoor Initializer is similar to using it in C. There is a special new constructor named _wrapObj that takes the private data pointer.

Of course, dynamically allocating data in fortran 77 is tricky, and requires very close cooperation with the Impl class that uses the data. Most of the complexity of this example code is caused by those problems, not so much the Backdoor Initializer itself.

Since we need to store 2 strings and an integer, we create 3 sidl arrays to hold the private data. We create an opaque array of 2 elements called pdata to hold the other two arrays. Then we create a string array of 2 elements called a_string, and an integer array of 1 element called a_int. d_string is element 0 of the string array, and d_ctortest is element 1. We then place a_string into pdata as element 0, and a_int in pdata as element 1. We then call _wrapObj, which takes pdata as an in argument as the first argument, and the object we are creating, data, as an out argument as the second argument.

Notice that we don’t have to include an Impl files to fortran 77, since, there aren’t actually any types.

Fairly complex, but here’s the client code from wraptest.f:

and the Impl side code from wrapper_Data_Impl.f

20.6  The Backdoor Initializer in Fortran 90/95

The Fortran 90/95 backdoor initializer is very similar to C. Fortran 90/95 also has a _wrapObj, but it is actually defined in the wrapper_Data_Mod.F90 file, along with the private data type definition.

Here is the private data definition from wrapper_Data_Mod.F90:

Here is the client code from wraptest.F90. Notice wrapper_Data_impl is used. From wraptest.F90:

Finally, the Impl code from wrapper_Data_Impl.F90:

20.7  The Backdoor Initializer in C++

In Object Oriented languages there is no _wrapObj method exposed to the user. Instead, the same functionality is achieved simply by calling “new” on the Impl class. Interestingly, this means the constructor functionality is NOT placed in a Babel ctor method, but is, instead, actually in the default object constructor.

Here is the private data definition from wrapper_Data_Impl.hxx:

Here is the client code from wraptest.cxx. Notice wrapper_Data_Impl is included.

Finally, the Impl code from wrapper_Data_Impl.cxx, notice where the constructor code is placed.

20.8  The Backdoor Initializer in Java

In Object Oriented languages there is no _wrapObj method exposed to the user. Instead, the same functionality is achieved simply by calling “new” on the Impl class. Interestingly, this means the constructor functionality is NOT placed in a Babel ctor method, but is, instead, actually in the default object constructor.

Here is an excerpt from the class definition for wrapper.Data_Impl:

Here is the client code from WrapTest.java:

20.9  The Backdoor Initializer in Python

In Object Oriented languages there is no _wrapObj method exposed to the user. Instead, the same functionality is achieved simply by calling “new” on the Impl class.

However, writing the Python backdoor constructor is a little trickier than Java or C++. This is because there is no overloading in Python, so multiple constructors were a problem. Instead, the class implementor needs to determine if the object is being constructed directly by the user, or through the normal Babel process. This can be achieved with an if statement. If the argument IORself == None, then the user has called the backdoor constructor, if IORself != None, it is a normal Babel construction.

Here is an excerpt from the class definition for wrapper.Data_Impl.Data:

Here is the client code from WrapTest.java: