Changes and Additions, July 2007

• Updates for omniORB 4.1.1.

Changes and Additions, June 2005

• New omniORB 4.1 features.

Changes and Additions, October 2004

• Packaging stubs into DLLs.

Changes and Additions, July 2004

• Minor updates.

Changes and Additions, November 2002

• Per thread timeouts.
• Implement missing interceptors.
• Minor fixes.

Changes and Additions, June 2002

• Updated to omniORB 4.0.

Contents

Chapter 1  Introduction

omniORB is an Object Request Broker (ORB) that implements the 2.6 specification of the Common Object Request Broker Architecture (CORBA) [OMG01]¹. It has passed the Open Group CORBA compliant testsuite (for CORBA 2.1) and was one of the three ORBs to be granted the CORBA brand in June 1999².

This user guide tells you how to use omniORB to develop CORBA applications. It assumes a basic understanding of CORBA.

In this chapter, we give an overview of the main features of omniORB and what you need to do to setup your environment to run omniORB.

1.1  Features

1.1.1  Multithreading

omniORB is fully multithreaded. To achieve low call overhead, unnecessary call-multiplexing is eliminated. With the default policies, there is at most one call in-flight in each communication channel between two address spaces at any one time. To do this without limiting the level of concurrency, new channels connecting the two address spaces are created on demand and cached when there are concurrent calls in progress. Each channel is served by a dedicated thread. This arrangement provides maximal concurrency and eliminates any thread switching in either of the address spaces to process a call. Furthermore, to maximise the throughput in processing large call arguments, large data elements are sent as soon as they are processed while the other arguments are being marshalled. With GIOP 1.2, large messages are fragmented, so the marshaller can start transmission before it knows how large the entire message will be.

From version 4.0 onwards, omniORB also supports a flexible thread pooling policy, and supports sending multiple interleaved calls on a single connection. This policy leads to a small amount of additional call overhead, compared to the default thread per connection model, but allows omniORB to scale to extremely large numbers of concurrent clients.

1.1.2  Portability

omniORB has always been designed to be portable. It runs on many flavours of Unix, Windows, several embedded operating systems, and relatively obscure systems such as OpenVMS and Fujitsu-Siemens BS2000. It is designed to be easy to port to new platforms. The IDL to C++ mapping for all target platforms is the same.

omniORB uses real C++ exceptions and nested classes. It keeps to the CORBA specification’s standard mapping as much as possible and does not use the alternative mappings for C++ dialects. The only exception is the mapping of IDL modules, which can use either namespaces or nested classes.

omniORB relies on native thread libraries to provide multithreading capability. A small class library (omnithread [Ric96]) is used to encapsulate the APIs of the native thread libraries. In application code, it is recommended but not mandatory to use this class library for thread management. It should be easy to port omnithread to any platform that either supports the POSIX thread standard or has a thread package that supports similar capabilities.

1.1.3  Missing features

omniORB is not (yet) a complete implementation of the CORBA 2.6 core. The following is a list of the most significant missing features.

• omniORB does not have its own Interface Repository. However, it can act as a client to an IfR. The omniifr project (http://omniifr.sourceforge.net/) aims to create an IfR for omniORB.
• omniORB supports interceptors, but not the standard Portable Interceptor API.

These features may be implemented in the short to medium term. It is best to check out the latest status on the omniORB home page (http://omniorb.sourceforge.net/).

1.2  Setting up your environment

To get omniORB running, you first need to install omniORB according to the instructions in the installation notes for your platform. Most Unix platforms can use the Autoconf configure script to automate the configuration process.

Once omniORB is installed in a suitable location, you must configure it according to your required set-up. The configuration can be set with a configuration file, environment variables, command-line arguments or, on Windows, the Windows registry.

• On Unix platforms, the omniORB runtime looks for the environment variable OMNIORB_CONFIG. If this variable is defined, it contains the pathname of the omniORB configuration file. If the variable is not set, omniORB will use the compiled-in pathname to locate the file (by default /etc/omniORB.cfg).
• On Win32 platforms (Windows NT, 2000, 95, 98), omniORB first checks the environment variable OMNIORB_CONFIG to obtain the pathname of the configuration file. If this is not set, it then attempts to obtain configuration data in the system registry. It searches for the data under the key HKEY_LOCAL_MACHINE\SOFTWARE\omniORB.

omniORB has a large number of parameters than can be configured. See chapter 4 for full details. The files sample.cfg and sample.reg contain an example configuration file and set of registry entries respectively.

To get all the omniORB examples running, the main thing you need to configure is the Naming service, omniNames. To do that, the configuration file or registry should contain an entry of the form

  InitRef = NameService=corbaname::my.host.name

See section 6.1.2 for full details of corbaname URIs.

1.3  Platform specific variables

To compile omniORB programs correctly, several C++ preprocessor defines must be specified to identify the target platform. On Unix platforms where omniORB was configured with Autoconf, the omniconfig.h file sets these for you. On other platforms, and Unix platforms when Autoconf is not used, you must specify the following defines:

The preprocessor defines for new platform ports not listed above can be found in the corresponding platform configuration files. For instance, the platform configuration file for Sun Solaris 2.6 is in mk/platforms/sun4_sosV_5.6.mk. The preprocessor defines to identify a platform are in the make variable IMPORT_CPPFLAGS.

In a single source multi-target environment, you can put the preprocessor defines as the command-line arguments for the compiler. If you are building for a single platform, you can edit include/omniconfig.h to add the definitions.

1

Most of the 2.6 features have been implemented. The features still missing in this release are listed in section 1.1.3. Where possible, backward compatibility has been maintained up to specification 2.0.

2

More information can be found at http://www.opengroup.org/press/7jun99_b.htm

Chapter 2  The Basics

In this chapter, we go through three examples to illustrate the practical steps to use omniORB. By going through the source code of each example, the essential concepts and APIs are introduced. If you have no previous experience with using CORBA, you should study this chapter in detail. There are pointers to other essential documents you should be familiar with.

If you have experience with using other ORBs, you should still go through this chapter because it provides important information about the features and APIs that are necessarily omniORB specific. With the Portable Object Adapter, there are very few omniORB specific details.

2.1  The Echo Object Example

Our example is an object which has only one method. The method simply echos the argument string. We have to:

1. define the object interface in IDL;
2. use the IDL compiler to generate the stub code¹;
3. provide the servant object implementation;
4. write the client code.

These examples are in the src/examples/echo directory of the omniORB distribution; there are several other examples one directory above that in src/examples.

2.2  Specifying the Echo interface in IDL

We define an object interface, called Echo, as follows:

If you are new to IDL, you can learn about its syntax in Chapter 3 of the CORBA 2.6 specification [OMG01]. For the moment, you only need to know that the interface consists of a single operation, echoString(), which takes a string as an input argument and returns a copy of the same string.

The interface is written in a file, called echo.idl. It is part of the CORBA standard that all IDL files should have the extension ‘.idl’, although omniORB does not enforce this.

For simplicity, the interface is defined in the global IDL namespace. You should avoid this practice for the sake of object reusability. If every CORBA developer defines their interfaces in the global IDL namespace, there is a danger of name clashes between two independently defined interfaces. Therefore, it is better to qualify your interfaces by defining them inside module names. Of course, this does not eliminate the chance of a name clash unless some form of naming convention is agreed globally. Nevertheless, a well-chosen module name can help a lot.

2.3  Generating the C++ stubs

From the IDL file, we use the IDL compiler to produce the C++ mapping of the interface. The IDL compiler for omniORB is called omniidl. Given the IDL file, omniidl produces two stub files: a C++ header file and a C++ source file. For example, from the file echo.idl, the following files are produced:

• echo.hh
• echoSK.cc

omniidl must be invoked with the -bcxx argument to tell it to generate C++ stubs. The following command line generates the stubs for echo.idl:

If you are using our make environment (ODE), you don’t need to invoke omniidl explicitly. In the example file dir.mk, we have the following line:

That is all we need to instruct ODE to generate the stubs. Remember, you won’t find the stubs in your working directory because all stubs are written into the stub directory at the top level of your build tree.

The full arguments to omniidl are detailed in chapter 5.

2.4  Object References and Servants

We contact a CORBA object through an object reference. The actual implementation of a CORBA object is termed a servant.

Object references and servants are quite separate entities, and it is important not to confuse the two. Client code deals purely with object references, so there can be no confusion; object implementation code must deal with both object references and servants. omniORB 4 uses distinct C++ types for object references and servants, so the C++ compiler will complain if you use a servant when an object reference is expected, or vice-versa.

2.5  A Quick Tour of the C++ stubs

The C++ stubs conform to the standard mapping defined in the CORBA specification [OMG03]. It is important to understand the mapping before you start writing any serious CORBA applications. Before going any further, it is worth knowing what the mapping looks like.

For the example interface Echo, the C++ mapping for its object reference is Echo_ptr. The type is defined in echo.hh. The relevant section of the code is reproduced below. The stub code produced by other ORBs will be functionally equivalent to omniORB’s, but will almost certainly look very different.

In a compliant application, the operations defined in an object interface should only be invoked via an object reference. This is done by using arrow (‘->’) on an object reference. For example, the call to the operation echoString() would be written as obj->echoString(mesg).

It should be noted that the concrete type of an object reference is opaque, i.e. you must not make any assumption about how an object reference is implemented. In our example, even though Echo_ptr is implemented as a pointer to the class _objref_Echo, it should not be used as a C++ pointer, i.e. conversion to void*, arithmetic operations, and relational operations including testing for equality using operator==, must not be performed on the type.

In addition to class _objref_Echo, the mapping defines three static member functions in the class Echo: _nil(), _duplicate(), and _narrow().

The _nil() function returns a nil object reference of the Echo interface. The following call is guaranteed to return TRUE:

Remember, CORBA::is_nil() is the only compliant way to check if an object reference is nil. You should not use the equality operator==. Many C++ ORBs use the null pointer to represent a nil object reference; omniORB does not.

The _duplicate() function returns a new object reference of the Echo interface. The new object reference can be used interchangeably with the old object reference to perform an operation on the same object. Duplications are required to satisfy the C++ mapping’s reference counting memory management.

All CORBA objects inherit from the generic object CORBA::Object. CORBA::Object_ptr is the object reference type for CORBA::Object. Any _ptr object reference is therefore conceptually inherited from CORBA::Object_ptr. In other words, an object reference such as Echo_ptr can be used in places where a CORBA::Object_ptr is expected.

The _narrow() function takes an argument of type CORBA::Object_ptr and returns a new object reference of the Echo interface. If the actual (runtime) type of the argument object reference can be narrowed to Echo_ptr, _narrow() will return a valid object reference. Otherwise it will return a nil object reference. Note that _narrow() performs an implicit duplication of the object reference, so the result must be released. Note also that _narrow() may involve a remote call to check the type of the object, so it may throw CORBA system exceptions such as COMM_FAILURE or OBJECT_NOT_EXIST.

To indicate that an object reference will no longer be accessed, you must call the CORBA::release() operation. Its signature is as follows:

Once you have called CORBA::release() on an object reference, you must no longer use that reference. This is because the associated resources may have been deallocated. Notice that we are referring to the resources associated with the object reference and not the servant object. Servant objects are not affected by the lifetimes of object references. In particular, servants are not deleted when all references to them have been released—CORBA does not perform distributed garbage collection.

As described above, the equality operator== should not be used on object references. To test if two object references are equivalent, the member function _is_equivalent() of the generic object CORBA::Object can be used. Here is an example of its usage:

You have now been introduced to most of the operations that can be invoked via Echo_ptr. The generic object CORBA::Object provides a few more operations and all of them can be invoked via Echo_ptr. These operations deal mainly with CORBA’s dynamic interfaces. You do not have to understand them in order to use the C++ mapping provided via the stubs.

Since object references must be released explicitly, their usage is prone to error and can lead to memory leakage. The mapping defines the object reference variable type to make life easier. In our example, the variable type Echo_var is defined².

The Echo_var is more convenient to use because it will automatically release its object reference when it is deallocated or when assigned a new object reference. For many operations, mixing data of type Echo_var and Echo_ptr is possible without any explicit operations or castings³. For instance, the operation echoString() can be called using the arrow (‘->’) on a Echo_var, as one can do with a Echo_ptr.

The usage of Echo_var is illustrated below:

2.5.1  Servant Object Implementation

Before the Portable Object Adapter (POA) specification, many of the details of how servant objects should be implemented and registered with the system were unspecified, so server-side code was not portable between ORBs. The POA specification rectifies that. omniORB 4 still supports the old omniORB 2.x BOA mapping, but you should always use the POA mapping for new code. BOA code and POA code can coexist within a single program. See section 3.1 for details of the BOA compatibility, and problems you may encounter.

For each object interface, a skeleton class is generated. In our example, the POA specification says that the skeleton class for interface Echo is named POA_Echo. A servant implementation can be written by creating an implementation class that derives from the skeleton class.

The skeleton class POA_Echo is defined in echo.hh. The relevant section of the code is reproduced below.

The code fragment shows the only member functions that can be used in the object implementation code. Other member functions are generated for internal use only. As with the code generated for object references, other POA-based ORBs will generate code which looks different, but is functionally equivalent to this.

echoString()

It is through this abstract function that an implementation class provides the implementation of the echoString() operation. Notice that its signature is the same as the echoString() function that can be invoked via the Echo_ptr object reference.

_this()

This function returns an object reference for the target object, provided the POA policies permit it. The returned value must be deallocated via CORBA::release(). See section 2.8 for an example of how this function is used.

2.6  Writing the servant implementation

You define an implementation class to provide the servant implementation. There is little constraint on how you design your implementation class except that it has to inherit from the stubs’ skeleton class and to implement all the abstract functions defined in the skeleton class. Each of these abstract functions corresponds to an operation of the interface. They are the hooks for the ORB to perform upcalls to your implementation.

Here is a simple implementation of the Echo object.

There are four points to note here:

Storage Responsibilities

A string, which is used both as an in argument and the return value of echoString(), is a variable size data type. Other examples of variable size data types include sequences, type ‘any’, etc. For these data types, you must be clear about whose responsibility it is to allocate and release the associated storage. As a rule of thumb, the client (or the caller to the implementation functions) owns the storage of all IN arguments, the object implementation (or the callee) must copy the data if it wants to retain a copy. For OUT arguments and return values, the object implementation allocates the storage and passes the ownership to the client. The client must release the storage when the variables will no longer be used. For details, please refer to the C++ mapping specification.

Multi-threading

As omniORB is fully multithreaded, multiple threads may perform the same upcall to your implementation concurrently. It is up to your implementation to synchronise the threads’ accesses to shared data. In our simple example, we have no shared data to protect so no thread synchronisation is necessary.

Alternatively, you can create a POA which has the SINGLE_THREAD_MODEL Thread Policy. This guarantees that all calls to that POA are processed sequentially.

Reference Counting

All servant objects are reference counted. The base PortableServer::ServantBase class from which all servant skeleton classes derive defines member functions named _add_ref() and _remove_ref()⁴. The reference counting means that an Echo_i instance will be deleted when no more references to it are held by application code or the POA itself. Note that this is totally separate from the reference counting which is associated with object references—a servant object is never deleted due to a CORBA object reference being released.

Instantiation

Servants are usually instantiated on the heap, i.e. using the new operator. However, they can also be created on the stack as automatic variables. If you do that, it is vital to make sure that the servant has been deactivated, and thus released by the POA, before the variable goes out of scope and is destroyed.

2.7  Writing the client

Here is an example of how an Echo_ptr object reference is used.

Briefly, the hello() function accepts a generic object reference. The object reference (obj) is narrowed to Echo_ptr. If the object reference returned by Echo::_narrow() is not nil, the operation echoString() is invoked. Finally, both the argument to and the return value of echoString() are printed to cerr.

The example also illustrates how T_var types are used. As was explained in the previous section, T_var types take care of storage allocation and release automatically when variables are reassigned or when the variables go out of scope.

In line 4, the variable e takes over the storage responsibility of the object reference returned by Echo::_narrow(). The object reference is released by the destructor of e. It is called automatically when the function returns. Lines 6 and 15 show how a Echo_var variable is used. As explained earlier, the Echo_var type can be used interchangeably with the Echo_ptr type.

The argument and the return value of echoString() are stored in CORBA::String_var variables src and dest respectively. The strings managed by the variables are deallocated by the destructor of CORBA::String_var. It is called automatically when the variable goes out of scope (as the function returns). Line 15 shows how CORBA::String_var variables are used. They can be used in place of a string (for which the mapping is char*)⁵. As used in line 12, assigning a constant string (const char*) to a CORBA::String_var causes the string to be copied. On the other hand, assigning a char* to a CORBA::String_var, as used in line 15, causes the latter to assume the ownership of the string⁶.

Under the C++ mapping, T_var types are provided for all the non-basic data types. It is obvious that one should use automatic variables whenever possible both to avoid memory leaks and to maximise performance. However, when one has to allocate data items on the heap, it is a good practice to use the T_var types to manage the heap storage.

2.8  Example 1 — Colocated Client and Implementation

Having introduced the client and the object implementation, we can now describe how to link up the two via the ORB and POA. In this section, we describe an example in which both the client and the object implementation are in the same address space. In the next two sections, we shall describe the case where the two are in different address spaces.

The code for this example is reproduced below:

The example illustrates several important interactions among the ORB, the POA, the servant, and the client. Here are the details:

2.8.1  ORB initialisation

Line 4

The ORB is initialised by calling the CORBA::ORB_init() function. The function uses the optional 3rd argument to determine which ORB should be returned. Unless you are using omniORB specific features, it is usually best to leave it out, and get the default ORB. To explicitly ask for omniORB 4.x, this argument must be ‘omniORB4’⁷.

CORBA::ORB_init() takes the list of command line arguments and processes any that start ‘-ORB’. It removes these arguments from the list, so application code does not have to deal with them.

If any error occurs during ORB initialisation, such as invalid ORB arguments, or an invalid configuration file, the CORBA::INITIALIZE system exception is raised.

2.8.2  Obtaining the Root POA

Lines 6–7

To activate our servant object and make it available to clients, we must register it with a POA. In this example, we use the Root POA, rather than creating any child POAs. The Root POA is found with orb->resolve_initial_references(), which returns a plain CORBA::Object. In line 7, we narrow the reference to the right type for a POA.

A POA’s behaviour is governed by its policies. The Root POA has suitable policies for many simple servers, and closely matches the ‘policies’ used by omniORB 2’s BOA. See Chapter 11 of the CORBA 2.6 specification[OMG01] for details of all the POA policies which are available.

2.8.3  Object initialisation

Line 9

An instance of the Echo servant is initialised using the new operator.

Line 10

The servant object is activated in the Root POA using poa->activate_object(), which returns an object identifier (of type PortableServer::ObjectId*). The object id must be passed back to various POA operations. The caller is responsible for freeing the object id, so it is assigned to a _var type.

Line 12

The object reference is obtained from the servant object by calling _this(). Like all object references, the return value of _this() must be released by CORBA::release() when it is no longer needed. In this case, we assign it to a _var type, so the release is implicit at the end of the function.

One of the important characteristics of an object reference is that it is completely location transparent. A client can invoke on the object using its object reference without any need to know whether the servant object is colocated in the same address space or is in a different address space.

In the case of colocated client and servant, omniORB is able to short-circuit the client calls so they do not involve IIOP. The calls still go through the POA, however, so the various POA policies affect local calls in the same way as remote ones. This optimisation is applicable not only to object references returned by _this(), but to any object references that are passed around within the same address space or received from other address spaces via remote calls.

Line 13

The server code releases the reference it holds to the servant object. The only reference to that object is now held by the POA (it gained the reference on the call to activate_object()), so when the object is deactivated (or the POA is destroyed), the servant object will be deleted automatically. After this point, the code must no longer use the myecho pointer.

2.8.4  Activating the POA

Lines 15–16

POAs are initially in the holding state, meaning that incoming requests are blocked. Lines 15 and 16 acquire a reference to the POA’s POA manager, and use it to put the POA into the active state. Incoming requests are now served. Failing to activate the POA is one of the most common programming mistakes. If your program appears deadlocked, make sure you activated the POA!

2.8.5  Performing a call

Line 18

At long last, we can call hello() with this object reference. The argument is widened implicitly to the generic object reference CORBA::Object_ptr.

2.8.6  ORB destruction

Line 20

Shutdown the ORB permanently. This call causes the ORB to release all its resources, e.g. internal threads, and also to deactivate any servant objects which are currently active. When it deactivates the Echo_i instance, the servant’s reference count drops to zero, so the servant is deleted.

This call is particularly important when writing a CORBA DLL on Windows NT that is to be used from ActiveX. If this call is absent, the application will hang when the CORBA DLL is unloaded.

2.9  Example 2 — Different Address Spaces

In this example, the client and the object implementation reside in two different address spaces. The code of this example is almost the same as the previous example. The only difference is the extra work which needs to be done to pass the object reference from the object implementation to the client.

The simplest (and quite primitive) way to pass an object reference between two address spaces is to produce a stringified version of the object reference and to pass this string to the client as a command-line argument. The string is then converted by the client into a proper object reference. This method is used in this example. In the next example, we shall introduce a better way of passing the object reference using the CORBA Naming Service.

2.9.1  Object Implementation: Making a Stringified Object Reference

The main() function of the server side is reproduced below. The full listing (eg2_impl.cc) can be found at the end of this chapter.

The stringified object reference is obtained by calling the ORB’s object_to_string() function (line 13). This results in a string starting with the signature ‘IOR:’ and followed by some hexadecimal digits. All CORBA 2 compliant ORBs are able to convert the string into its internal representation of a so-called Interoperable Object Reference (IOR). The IOR contains the location information and a key to uniquely identify the object implementation in its own address space. From the IOR, an object reference can be constructed.

2.9.2  Client: Using a Stringified Object Reference

The stringified object reference is passed to the client as a command-line argument. The client uses the ORB’s string_to_object() function to convert the string into a generic object reference (CORBA::Object_ptr). The relevant section of the code is reproduced below. The full listing (eg2_clt.cc) can be found at the end of this chapter.

2.9.3  Catching System Exceptions

When omniORB detects an error condition, it may raise a system exception. The CORBA specification defines a series of exceptions covering most of the error conditions that an ORB may encounter. The client may choose to catch these exceptions and recover from the error condition⁸. For instance, the code fragment, shown in section 2.9.2, catches the TRANSIENT system exception which indicates that the object could not be contacted at the time of the call, usually meaning the server is not running.

All system exceptions inherit from CORBA::SystemException. With compilers that properly support RTTI⁹, a single catch of CORBA::SystemException will catch all the different system exceptions thrown by omniORB.

When omniORB detects an internal error such as corrupt data or invalid conditions, it raises the exception omniORB::fatalException. When this exception is raised, it is not sensible to proceed with any operation that involves the ORB’s runtime. It is best to exit the program immediately. The exception structure carried by omniORB::fatalException contains the exact location (the file name and the line number) where the exception is raised. In most cases, fatalExceptions occur due to incorrect behaviour by the application code, but they may be caused by bugs in omniORB.

2.9.4  Lifetime of a CORBA object

CORBA objects are either transient or persistent. The majority are transient, meaning that the lifetime of the CORBA object (as contacted through an object reference) is the same as the lifetime of its servant object. Persistent objects can live beyond the destruction of their servant object, the POA they were created in, and even their process. Persistent objects are, of course, only contactable when their associated servants are active, or can be activated by their POA with a servant manager¹⁰. A reference to a persistent object can be published, and will remain valid even if the server process is restarted.

A POA’s Lifespan Policy determines whether objects created within it are transient or persistent. The Root POA has the TRANSIENT policy.

An alternative to creating persistent objects is to register object references in a naming service and bind them to fixed path names. Clients can bind to the object implementations at run time by asking the naming service to resolve the path names to the object references. CORBA defines a standard naming service, which is a component of the Common Object Services (COS) [OMG98], that can be used for this purpose. The next section describes an example of how to use the COS Naming Service.

2.10  Example 3 — Using the Naming Service

In this example, the object implementation uses the Naming Service [OMG98] to pass on the object reference to the client. This method is far more practical than using stringified object references. The full listing of the object implementation (eg3_impl.cc) and the client (eg3_clt.cc) can be found at the end of this chapter.

The names used by the Naming service consist of a sequence of name components. Each name component has an id and a kind field, both of which are strings. All name components except the last one are bound to a naming context. A naming context is analogous to a directory in a filing system: it can contain names of object references or other naming contexts. The last name component is bound to an object reference.

Sequences of name components can be represented as a flat string, using ‘.’ to separate the id and kind fields, and ‘/’ to separate name components from each other¹¹. In our example, the Echo object reference is bound to the stringified name ‘test.my_context/Echo.Object’.

The kind field is intended to describe the name in a syntax-independent way. The naming service does not interpret, assign, or manage these values. However, both the name and the kind attribute must match for a name lookup to succeed. In this example, the kind values for test and Echo are chosen to be ‘my_context’ and ‘Object’ respectively. This is an arbitrary choice as there is no standardised set of kind values.

2.10.1  Obtaining the Root Context Object Reference

The initial contact with the Naming Service can be established via the root context. The object reference to the root context is provided by the ORB and can be obtained by calling resolve_initial_references(). The following code fragment shows how it is used:

Remember, omniORB constructs its internal list of initial references at initialisation time using the information provided in the configuration file omniORB.cfg, or given on the command line. If this file is not present, the internal list will be empty and resolve_initial_references() will raise a CORBA::ORB::InvalidName exception.

2.10.2  The Naming Service Interface

It is beyond the scope of this chapter to describe in detail the Naming Service interface. You should consult the CORBA services specification [OMG98] (chapter 3). The code listed in eg3_impl.cc and eg3_clt.cc are good examples of how the service can be used. Please spend time to study the examples carefully.

2.11  Example 4 — Using tie implementation templates

omniORB supports tie implementation templates as an alternative way of providing servant classes. If you use the -Wbtp option to omniidl, it generates an extra template class for each interface. This template class can be used to tie a C++ class to the skeleton class of the interface.

The source code in eg3_tieimpl.cc at the end of this chapter illustrates how the template class can be used. The code is almost identical to eg3_impl.cc with only a few changes.

Firstly, the servant class Echo_i does not inherit from any stub classes. This is the main benefit of using the template class because there are applications in which it is difficult to require every servant class to derive from CORBA classes.

Secondly, the instantiation of a CORBA object now involves creating an instance of the implementation class and an instance of the template. Here is the relevant code fragment:

For interface Echo, the name of its tie implementation template is POA_Echo_tie. The template parameter is the servant class that contains an implementation of each of the operations defined in the interface. As used above, the tie template takes ownership of the Echo_i instance, and deletes it when the tie object goes out of scope. The tie constructor has an optional boolean argument (defaulted to true) which indicates whether or not it should delete the servant object. For full details of using tie templates, see the CORBA C++ mapping specification.

2.12  Source Listings

2.12.1  eg1.cc

2.12.2  eg2_impl.cc

2.12.3  eg2_clt.cc

2.12.4  eg3_impl.cc

2.12.5  eg3_clt.cc

2.12.6  eg3_tieimpl.cc

1

The stub code is the C++ code that provides the object mapping as defined in the CORBA specification.

2

In omniORB, all object reference variable types are instantiated from the template type _CORBA_ObjRef_Var.

3

However, the implementation of the type conversion operator between Echo_var and Echo_ptr varies slightly among different C++ compilers; you may need to do an explicit cast if the compiler complains about the conversion being ambiguous.

4

In the previous 1.0 version of the C++ mapping, servant reference counting was optional, chosen by inheriting from a mixin class named RefCountServantBase. That has been deprecated in the 1.1 version of the C++ mapping, but the class is still available as an empty struct, so existing code that inherits from RefCountServantBase will continue to work.

5

A conversion operator of CORBA::String_var converts a CORBA::String_var to a char*.

6

Please refer to the C++ mapping specification for details of the String_var mapping.

7

For backwards compatibility, the ORB identifiers ‘omniORB2’ and ‘omniORB3’ are also accepted.

8

If a system exception is not caught, the C++ runtime will call the terminate() function. This function is defaulted to abort the whole process and on some systems will cause a core file to be produced.

9

Run Time Type Identification

10

The POA itself can be activated on demand with an adapter activator.

11

There are escaping rules to cope with id and kind fields which contain ‘.’ and ‘/’ characters. See chapter 6 of this manual, and chapter 3 of the CORBA services specification, as updated for the Interoperable Naming Service [OMG00].

Chapter 3  C++ language mapping

Now that you are familiar with the basics, it is important to familiarise yourself with the standard IDL to C++ language mapping. The mapping is described in detail in [OMG03]. If you have not done so, you should obtain a copy of the document and use that as the programming guide to omniORB.

The specification is not an easy read. The alternative is to use one of the books on CORBA programming that has begun to appear. For instance, Henning and Vinoski’s ‘Advanced CORBA Programming with C++’ [HV99] includes many example code bits to illustrate how to use the C++ mapping.

3.1  omniORB 2 BOA compatibility

If you use the -WbBOA option to omniidl, it will generate skeleton code with the same interface as the old omniORB 2 BOA mapping, as well as code to be used with the POA. Note that since the major problem with the BOA specification was that server code was not portable between ORBs, it is unlikely that omniORB 4.1’s BOA compatibility will help you much if you are moving from a different BOA-based ORB.

The BOA compatibility permits the majority of BOA code to compile without difficulty. However, there are a number of constructs which relied on omniORB 2 implementation details which no longer work.

• omniORB 2 did not use distinct types for object references and servants, and often accepted a pointer to a servant when the CORBA specification says it should only accept an object reference. Such code will not compile under omniORB 4.1.
• The reverse is true for BOA::obj_is_ready(). It now only works when passed a pointer to a servant object, not an object reference. The more commonly used mechanism of calling _obj_is_ready(boa) on the servant object still works as expected.
• It used to be the case that the skeleton class for interface I (_sk_I) was derived from class I. This meant that the names of any types declared in the interface were available in the scope of the skeleton class. This is no longer true. If you have an interface:
  interface I { struct S { long a,b; }; S op(); };

  then where before the implementation code might have been:

  class I_impl : public virtual _sk_I { S op(); // _sk_I is derived from I }; I::S I_impl::op() { S ret; // ... }

  it is now necessary to fully qualify all uses of S:

  class I_impl : public virtual _sk_I { I::S op(); // _sk_I is not derived from I }; I::S I_impl::op() { I::S ret; // ... }
• The proprietary omniORB 2 LifeCycle extensions are no longer supported. All of the facilities it offered can be implemented with the POA interfaces, and the omniORB::LOCATION_FORWARD exception (see section 4.8). Code which used the old interfaces will have to be rewritten.

3.2  omniORB 3.0 compatibility

omniORB 4.1 is almost completely source-code compatible with omniORB 3.0. There are two main cases where code may have to change. The first is code that uses the omniORB API, some aspects of which have changed. The omniORB configuration file also has a new format. See the next chapter for details of the new API and configuration file.

The second case of code that may have to change is code using the Dynamic Any interfaces. The standard changed quite significantly between CORBA 2.2 and CORBA 2.3; omniORB 3.0 supported the old CORBA 2.2 interfaces; omniORB 4.1 uses the new mapping. The changes are largely syntax changes, rather than semantic differences.

3.3  omniORB 4.0 compatibility

omniORB 4.1 is source-code compatible with omniORB 4.0, with four exceptions:

1. As required by the 1.1 version of the CORBA C++ mapping specification, the RefCountServantBase class has been deprecated, and the reference counting functionality moved into ServantBase. For backwards compatibility, RefCountServantBase still exists, but is now defined as an empty struct. Most code will continue to work unchanged, but code that explicitly calls RefCountServantBase::_add_ref() or _remove_ref() will no longer compile.
2. omniORB 4.0 had an option for Any extraction semantics that was compatible with omniORB 2.7, where ownership of extracted values was not maintained by the Any. That option is no longer available.
3. The members of the clientSendRequest interceptor have been changed, replacing all the separate variables with a single member of type GIOP_C. All the values previously available can be accessed through the GIOP_C instance.
4. The C++ mapping contains Any insertion operators for sequence types that are passed by pointer, which cause the Any to take ownership of the inserted sequence. In omniORB 4.0 and earlier, the sequence was immediately marshalled into the Any’s internal buffer, and the sequence was deleted. In omniORB 4.1, the sequence pointer is stored by the Any, and the sequence is deleted later when the Any is destroyed.

   For most uses, this change is not visible to application code. However, if a sequence is constructed using an application-supplied buffer with the release flag set to false (meaning that the application continues to own the buffer), it is now important that the buffer is not deleted or modified while the Any exists, since the Any continues to refer to the buffer contents. This change means that code that worked with omniORB 4.0 may now fail with 4.1, with the Any seeing modified data or the process crashing due to accessing deleted data. To avoid this situation, use the alternative Any insertion operator using a const reference, which copies the sequence.

Chapter 4  omniORB configuration and API

omniORB 4.1 has a wide range of parameters that can be configured. They can be set in the configuration file / Windows registry, as environment variables, on the command line, or within a proprietary extra argument to CORBA::ORB_init(). A few parameters can be configured at run time. This chapter lists all the configuration parameters, and how they are used.

4.1  Setting parameters

When CORBA::ORB_init() is called, the value for each configuration parameter is searched for in the following order:

1. Command line arguments
2. ORB_init() options
3. Environment variables
4. Configuration file / Windows registry
5. Built-in defaults

4.1.1  Command line arguments

Command line arguments take the form ‘-ORBparameter’, and usually expect another argument. An example is ‘-ORBtraceLevel 10’.

4.1.2  ORB_init() parameter

ORB_init()’s extra argument accepts an array of two-dimensional string arrays, like this:

4.1.3  Environment variables

Environment variables consist of the parameter name prefixed with ‘ORB’. Using bash, for example

4.1.4  Configuration file

The best way to understand the format of the configuration file is to look at the sample.cfg file in the omniORB distribution. Each parameter is set on a single line like

traceLevel = 10

Some parameters can have more than one value, in which case the parameter name may be specified more than once, or you can leave it out:

InitRef = NameService=corbaname::host1.example.com
        = InterfaceRepository=corbaloc::host2.example.com:1234/IfR

4.1.5  Windows registry

On Windows, configuration parameters can be stored in the registry, under the key HKEY_LOCAL_MACHINE\SOFTWARE\omniORB.

The file sample.reg shows the settings that can be made. It can be edited and then imported into regedit.

4.2  Tracing options

The following options control debugging trace output.

traceLevel    default = 1

omniORB can output tracing and diagnostic messages to the standard error stream. The following levels are defined:

The trace level is cumulative, so at level 40, all trace messages are output.

traceExceptions    default = 0

If the traceExceptions parameter is set true, all system exceptions are logged as they are thrown, along with details about where the exception is thrown from. This parameter is enabled by default if the traceLevel is set to 10 or more.

traceInvocations    default = 0

If the traceInvocations parameter is set true, all local and remote invocations are logged, in addition to any logging that may have been selected with traceLevel.

traceInvocationReturns    default = 0

If the traceInvocationReturns parameter is set true, a log message is output as an operation invocation returns. In conjunction with traceInvocations and traceTime (described below), this provides a simple way of timing CORBA calls within your application.

traceThreadId    default = 0

If traceThreadId is set true, all trace messages are prefixed with the id of the thread outputting the message. This can be handy for tracking down race conditions, but it adds significant overhead to the logging function so it is turned off by default.

traceTime    default = 0

If traceTime is set true, all trace messages are prefixed with the time. This is useful, but on some platforms it adds a very large overhead, so it is turned off by default.

traceFile    default =

omniORB’s tracing is normally sent to stderr. if traceFile it set, the specified file name is used for trace messages.

4.2.1  Tracing API

The tracing parameters can be modified at runtime by assigning to the following variables

Log messages can be sent somewhere other than stderr by registering a logging function which is called with the text of each log message:

The log function must not make any CORBA calls, since that could lead to infinite recursion as outputting a log message caused other log messages to be generated, and so on.

4.3  Miscellaneous global options

These options control miscellaneous features that affect the whole ORB runtime.

dumpConfiguration    default = 0

If set true, the ORB dumps the values of all configuration parameters at start-up.

scanGranularity    default = 5

As explained in chapter 8, omniORB regularly scans incoming and outgoing connections, so it can close unused ones. This value is the granularity in seconds at which the ORB performs its scans. A value of zero turns off the scanning altogether.

nativeCharCodeSet    default = ISO-8859-1

The native code set the application is using for char and string. See chapter 9.

nativeWCharCodeSet    default = UTF-16

The native code set the application is using for wchar and wstring. See chapter 9.

copyValuesInLocalCalls    default = 1

Determines whether valuetype parameters in local calls are copied or not. See chapter 13.

abortOnInternalError    default = 0

If this is set true, internal fatal errors will abort immediately, rather than throwing the omniORB::fatalException exception. This can be helpful for tracking down bugs, since it leaves the call stack intact.

abortOnNativeException    default = 0

On Windows, ‘native’ exceptions such as segmentation faults and divide by zero appear as C++ exceptions that can be caught with catch (...). Setting this parameter to true causes such exceptions to abort the process instead.

maxSocketSend
maxSocketRecv
On some platforms, calls to send() and recv() have a limit on the buffer size that can be used. These parameters set the limits in bytes that omniORB uses when sending / receiving bulk data.

The default values are platform specific. It is unlikely that you will need to change the values from the defaults.

The minimum valid limit is 1KB, 1024 bytes.

socketSendBuffer    default = -1 or 16384

On Windows, there is a kernel buffer used during send operations. A bug in Windows means that if a send uses the entire kernel buffer, a select() on the socket blocks until all the data has been acknowledged by the receiver, resulting in dreadful performance. This parameter modifies the socket send buffer from its default (8192 bytes on Windows) to the value specified. If this parameter is set to -1, the socket send buffer is left at the system default.

On Windows, the default value of this parameter is 16384 bytes; on all other platforms the default is -1.

validateUTF8    default = 0

When transmitting a string that is supposed to be UTF-8, omniORB usually passes it directly, assuming that it is valid. With this parameter set true, omniORB checks that all UTF-8 strings are valid, and throws DATA_CONVERSION if not.

4.4  Client side options

These options control aspects of client-side behaviour.

InitRef    default = none

Specify objects available from ORB::resolve_initial_references(). The arguments take the form <key>=<uri>, where key is the name given to resolve_initial_references() and uri is a valid CORBA object reference URI, as detailed in chapter 6.

DefaultInitRef    default = none

Specify the default URI prefix for resolve_initial_references(), as explained in chapter 6.

clientTransportRule    default = * unix,tcp,ssl

Used to specify the way the client contacts a server, depending on the server’s address. See section 8.7.1 for details.

clientCallTimeOutPeriod    default = 0

Call timeout in milliseconds for the client side. If a call takes longer than the specified number of milliseconds, the ORB closes the connection to the server and raises a TRANSIENT exception. A value of zero means no timeout; calls can block for ever. See section 8.3.1 for more information about timeouts.

Note: omniORB 3 had timeouts specified in seconds; omniORB 4.0 and later use milliseconds for timeouts.

clientConnectTimeOutPeriod    default = 0

The timeout that is used in the case that a new network connection is established to the server. A value of zero means that the normal call timeout is used. See section 8.3.1 for more information about timeouts.

supportPerThreadTimeOut    default = 0

If this parameter is set true, timeouts can be set on a per thread basis, as well as globally and per object. Checking per-thread storage has a noticeable performance impact, so it is turned off by default.

resetTimeoutOnRetries    default = 0

If true, the call timeout is reset when an exception handler causes a call to be retried. If false, the timeout is not reset, and therefore applies to the call as a whole, rather than to each individual call attempt.

outConScanPeriod    default = 120

Idle timeout in seconds for outgoing (i.e. client initiated) connections. If a connection has been idle for this amount of time, the ORB closes it. See section 8.5.

maxGIOPConnectionPerServer    default = 5

The maximum number of concurrent connections the ORB will open to a single server. If multiple threads on the client call the same server, the ORB opens additional connections to the server, up to the maximum specified by this parameter. If the maximum is reached, threads are blocked until a connection becomes free for them to use.

oneCallPerConnection    default = 1

When this parameter is set to true (the default), the ORB will only send a single call on a connection at a time. If multiple client threads invoke on the same server, multiple connections are opened, up to the limit specified by maxGIOPConnectionPerServer. With this parameter set to false, the ORB will allow concurrent calls on a single connection. This saves connection resources, but requires slightly more management work for both client and server. Some server-side ORBs (including omniORB versions before 4.0) serialise all calls on a single connection.

maxInterleavedCallsPerConnection    default = 5

The maximum number of calls that can be interleaved on a connection. If more concurrent calls are made, they are queued.

offerBiDirectionalGIOP    default = 0

If set true, the client will indicate to servers that it is willing to accept callbacks on client-initiated connections using bidirectional GIOP, provided the relevant POA policies are set. See section 8.8.

diiThrowsSysExceptions    default = 0

If this is true, DII functions throw system exceptions; if it is false, system exceptions that occur are passed through the Environment object.

verifyObjectExistsAndType    default = 1

By default, omniORB uses the GIOP LOCATE_REQUEST message to verify the existence of an object prior to the first invocation. In the case that the full type of the object is not known, it instead calls the _is_a() operation to check the object’s type. Some ORBs have bugs that mean one or other of these operations fail. Setting this parameter false prevents omniORB from making these calls.

giopTargetAddressMode    default = 0

GIOP 1.2 supports three addressing modes for contacting objects. This parameter selects the mode that omniORB uses. A value of 0 means GIOP::KeyAddr; 1 means GIOP::ProfileAddr; 2 means GIOP::ReferenceAddr.

immediateAddressSwitch    default = 0

If true, the client will immediately switch to use a new address to contact an object after a failure. If false (the default), the current address will be retried in certain circumstances.

bootstrapAgentHostname    default = none

If set, this parameter indicates the hostname to use for look-ups using the obsolete Sun bootstrap agent. This mechanism is superseded by the interoperable naming service.

bootstrapAgentPort    default = 900

The port number for the obsolete Sun bootstrap agent.

principal    default = none

GIOP 1.0 and 1.1 have a request header field named ‘principal’, which contains a sequence of octets. It was never defined what it should mean, and its use is now deprecated; GIOP 1.2 has no such field. Some systems (e.g. Gnome) use the principal field as a primitive authentication scheme. This parameter sets the data omniORB uses in the principal field. The default is an empty sequence.

4.5  Server side options

These parameters affect server-side operations.

endPoint             default = giop:tcp::
endPointNoListen
endPointPublish
endPointNoPublish
endPointPublishAllIFs
These options determine the end-points the ORB should listen on, and the details that should be published in IORs. See chapter 8 for details.

serverTransportRule    default = * unix,tcp,ssl

Configure the rules about whether a server should accept an incoming connection from a client. See section 8.7.2 for details.

serverCallTimeOutPeriod    default = 0

This timeout is used to catch the situation that the server starts receiving a request, but the end of the request never comes. If a calls takes longer than the specified number of milliseconds to arrive, the ORB shuts the connection. A value of zero means never timeout.

inConScanPeriod    default = 180

Idle timeout in seconds for incoming. If a connection has been idle for this amount of time, the ORB closes it. See section 8.5.

threadPerConnectionPolicy    default = 1

If true (the default), the ORB dedicates one server thread to each incoming connection. Setting it false means the server should use a thread pool.

maxServerThreadPerConnection    default = 100

If the client multiplexes several concurrent requests on a single connection, omniORB uses extra threads to service them. This parameter specifies the maximum number of threads that are allowed to service a single connection at any one time.

maxServerThreadPoolSize    default = 100

The maximum number of threads the server will allocate to do various tasks, including dispatching calls in the thread pool mode. This number does not include threads dispatched under the thread per connection server mode.

threadPerConnectionUpperLimit    default = 10000

If the threadPerConnectionPolicy parameter is true, the ORB can automatically transition to thread pool mode if too many connections arrive. This parameter sets the number of connections at which thread pooling is started. The default of 10000 is designed to mean that it never happens.

threadPerConnectionLowerLimit    default = 9000

If thread pooling was started because the number of connections hit the upper limit, this parameter determines when thread per connection should start again.

threadPoolWatchConnection    default = 1

After dispatching an upcall in thread pool mode, the thread that has just performed the call can watch the connection for a short time before returning to the pool. This leads to less thread switching for a series of calls from a single client, but is less fair if there are concurrent clients. The connection is watched if the number of threads concurrently handling the connection is <= the value of this parameter. i.e. if the parameter is zero, the connection is never watched; if it is 1, the last thread managing a connection watches it; if 2, the connection is still watched if there is one other thread still in an upcall for the connection, and so on.

See section 8.4.2.

connectionWatchPeriod    default = 50000

For each endpoint, the ORB allocates a thread to watch for new connections and to monitor existing connections for calls that should be handed by the thread pool. The thread blocks in select() or similar for a period, after which it re-scans the lists of connections it should watch. This parameter is specified in microseconds.

connectionWatchImmediate    default = 0

When a thread handles an incoming call, it unmarshals the arguments then marks the connection as watchable by the connection watching thread, in case the client sends a concurrent call on the same connection. If this parameter is set to the default false, the connection is not actually watched until the next connection watch period (determined by the connectionWatchPeriod parameter). If this parameter is set true, the connection watching thread is immediately signalled to watch the connection. That leads to faster interactive response to clients that multiplex calls, but adds significant overhead along the call chain.

Note that this setting has no effect on Windows, since it has no mechanism for signalling the connection watching thread.

acceptBiDirectionalGIOP    default = 0

Determines whether a server will ever accept clients’ offers of bidirectional GIOP connections. See section 8.8.

unixTransportDirectory    default = /tmp/omni-%u

(Unix platforms only). Selects the location used to store Unix domain sockets. The ‘%u’ is expanded to the user name.

unixTransportPermission    default = 0777

(Unix platforms only). Determines the octal permission bits for Unix domain sockets. By default, all users can connect to a server, just as with TCP.

supportCurrent    default = 1

omniORB supports the PortableServer::Current interface to provide thread context information to servants. Supporting current has a small but noticeable run-time overhead due to accessing thread specific storage, so this option allows it to be turned off.

objectTableSize    default = 0

Hash table size of the Active Object Map. If this is zero, the ORB uses a dynamically resized open hash table. This is normally the best option, but it leads to less predictable performance since any operation which adds or removes a table entry may trigger a resize. If set to a non-zero value, the hash table has the specified number of entries, and is never resized. Note that the hash table is open, so this does not limit the number of active objects, just how efficiently they can be located.

poaHoldRequestTimeout    default = 0

If a POA is put in the HOLDING state, calls to it will be timed out after the specified number of milliseconds, by raising a TRANSIENT exception. Zero means no timeout.

poaUniquePersistentSystemIds    default = 1

The POA specification requires that object ids in POAs with the PERSISTENT and SYSTEM_ID policies are unique between instantiations of the POA. Older versions of omniORB did not comply with that, and reused object ids. With this value true, the POA has the correct behaviour; with false, the POA uses the old scheme for compatibility.

idleThreadTimeout    default = 10

When a thread created by omniORB becomes idle, it is kept alive for a while, in case a new thread is required. Once a thread has been idle for the number of seconds specified in this parameter, it exits.

supportBootstrapAgent    default = 0

If set true, servers support the Sun bootstrap agent protocol.

4.5.1  Main thread selection

There is one server-side parameter that must be set with an API function, rather than a normal configuration parameter:

POAs with the MAIN_THREAD policy dispatch calls on the ‘main’ thread. By default, omniORB assumes that the thread that initialised the omnithread library is the ‘main’ thread. To choose a different thread, call this function from the desired ‘main’ thread. The calling thread must have an omni_thread associated with it (i.e. it must have been created by omnithread, or omni_thread::create_dummy() must have been called). If it does not, the function throws CORBA::INITIALIZE.

Note that calls are only actually dispatched to the ‘main’ thread if ORB::run() or ORB::perform_work() is called from that thread.

4.6  GIOP and interoperability options

These options control omniORB’s use of GIOP, and cover some areas where omniORB can work around buggy behaviour by other ORBs.

maxGIOPVersion    default = 1.2

Choose the maximum GIOP version the ORB should support. Valid values are 1.0, 1.1 and 1.2.

giopMaxMsgSize    default = 2097152

The largest message, in bytes, that the ORB will send or receive, to avoid resource starvation. If the limit is exceeded, a MARSHAL exception is thrown. The size must be >= 8192.

strictIIOP    default = 1

If true, be strict about interpretation of the IIOP specification; if false, permit some buggy behaviour to pass.

lcdMode    default = 0

If true, select ‘Lowest Common Denominator’ mode. This disables various IIOP and GIOP features that are known to cause problems with some ORBs.

tcAliasExpand    default = 0

This flag is used to indicate whether TypeCodes associated with Anys should have aliases removed. This functionality is included because some ORBs will not recognise an Any containing a TypeCode with aliases to be the same as the actual type contained in the Any. Note that omniORB will always remove top-level aliases, but will not remove aliases from TypeCodes that are members of other TypeCodes (e.g. TypeCodes for members of structs etc.), unless tcAliasExpand is set to 1. There is a performance penalty when inserting into an Any if tcAliasExpand is set to 1.

useTypeCodeIndirections    default = 1

TypeCode Indirections reduce the size of marshalled TypeCodes, and are essential for recursive types, but some old ORBs do not support them. Setting this flag to false prevents the use of indirections (and, therefore, recursive TypeCodes).

acceptMisalignedTcIndirections    default = 0

If true, try to fix a mis-aligned indirection in a typecode. This is used to work around a bug in some old versions of Visibroker’s Java ORB.

4.7  System Exception Handlers

By default, all system exceptions that are raised during an operation invocation, with the exception of some cases of CORBA::TRANSIENT, are propagated to the application code. Some applications may prefer to trap these exceptions within the proxy objects so that the application logic does not have to deal with the error condition. For example, when a CORBA::COMM_FAILURE is received, an application may just want to retry the invocation until it finally succeeds. This approach is useful for objects that are persistent and have idempotent operations.

omniORB provides a set of functions to install exception handlers. Once they are installed, proxy objects will call these handlers when the associated system exceptions are raised by the ORB runtime. Handlers can be installed for CORBA::TRANSIENT, CORBA::COMM_FAILURE and CORBA::SystemException. This last handler covers all system exceptions other than the two covered by the first two handlers. An exception handler can be installed for individual proxy objects, or it can be installed for all proxy objects in the address space.

4.7.1  Minor codes

omniORB makes extensive use of exception minor codes to indicate the specific circumstances surrounding a system exception. The file include/omniORB4/minorCode.h contains definitions of all the minor codes used in omniORB, covering codes allocated in the CORBA specification, and ones specific to omniORB. In compilers with namespace support, the minor code constants appear in namespace omni; otherwise they are in the global scope.

Applications can use minor codes to adjust their behaviour according to the condition, e.g.

4.7.2  CORBA::TRANSIENT handlers

TRANSIENT exceptions can occur in many circumstances. One circumstance is as follows:

1. The client invokes on an object reference.
2. The object replies with a LOCATION_FORWARD message.
3. The client caches the new location and retries to the new location.
4. Time passes...
5. The client tries to invoke on the object again, using the cached, forwarded location.
6. The attempt to contact the object fails.
7. The ORB runtime resets the location cache and throws a TRANSIENT exception with minor code TRANSIENT_FailedOnForwarded.

In this situation, the default TRANSIENT exception handler retries the call, using the object’s original location. If the retry results in another LOCATION_FORWARD, to the same or a different location, and that forwarded location fails immediately, the TRANSIENT exception will occur again, and the pattern will repeat. With repeated exceptions, the handler starts adding delays before retries, with exponential back-off.

In all other circumstances, the default TRANSIENT handler just passes the exception on to the caller.

Applications can override the default behaviour by installing their own exception handler. The API to do so is summarised below:

The overloaded function installTransientExceptionHandler() can be used to install the exception handlers for CORBA::TRANSIENT. Two forms are available: the first form installs an exception handler for all object references except for those which have an exception handler installed by the second form, which takes an additional argument to identify the target object reference. The argument cookie is an opaque pointer which will be passed on by the ORB when it calls the exception handler.

An exception handler will be called by proxy objects with three arguments. The cookie is the opaque pointer registered by installTransientExceptionHandler(). The argument n_retries is the number of times the proxy has called this handler for the same invocation. The argument ex is the value of the exception caught. The exception handler is expected to do whatever is appropriate and return a boolean value. If the return value is TRUE(1), the proxy object retries the operation. If the return value is FALSE(0), the original exception is propagated into the application code. In the case of a TRANSIENT exception due to a failed location forward, the exception propagated to the application is the original exception that caused the TRANSIENT (e.g. a COMM_FAILURE or OBJECT_NOT_EXIST), rather than the TRANSIENT exception¹.

The following sample code installs a simple exception handler for all objects and for a specific object:

4.7.3  CORBA::COMM_FAILURE

If the ORB has successfully contacted an object at some point, and access to it subsequently fails (and the condition for TRANSIENT described above does not occur), the ORB raises a CORBA::COMM_FAILURE exception.

The default behaviour of the proxy objects is to propagate this exception to the application. Applications can override the default behaviour by installing their own exception handlers. The API to do so is summarised below:

The functions are equivalent to their counterparts for CORBA::TRANSIENT.

4.7.4  CORBA::SystemException

If a system exceptions other than TRANSIENT or COMM_FAILURE occurs, the default behaviour of the proxy objects is to propagate this exception to the application. Applications can override the default behaviour by installing their own exception handlers. The API to do so is summarised below:

The functions are equivalent to their counterparts for CORBA::TRANSIENT.

4.8  Location forwarding

Any CORBA operation invocation can return a LOCATION_FORWARD message to the caller, indicating that it should retry the invocation on a new object reference. The standard allows ServantManagers to trigger LOCATION_FORWARDs by raising the PortableServer::ForwardRequest exception, but it does not provide a similar mechanism for normal servants. omniORB provides the omniORB::LOCATION_FORWARD exception for this purpose. It can be thrown by any operation implementation.

The exception object consumes the object reference it is passed.

1

This is a change from omniORB 4.0 and earlier, where it was the TRANSIENT exception that was propagated to the application.

Chapter 5  The IDL compiler

omniORB’s IDL compiler is called omniidl. It consists of a generic front-end parser written in C++, and a number of back-ends written in Python. omniidl is very strict about IDL validity, so you may find that it reports errors in IDL which compiles fine with other IDL compilers.

The general form of an omniidl command line is:

omniidl [options] -b<back-end> [back-end options] <file 1> <file 2> …

5.1  Common options

The following options are common to all back-ends:

Most of these options are self explanatory, but some are not so obvious.

5.1.1  Preprocessor interactions

IDL is processed by the C preprocessor before omniidl parses it. omniidl always uses the GNU C preprocessor (which it builds with the name omnicpp). The -D, -U, and -I options are just sent to the preprocessor. Note that the current directory is not on the include search path by default—use ‘-I.’ for that. The -Y option can be used to specify a different preprocessor to omnicpp. Beware that line directives inserted by other preprocessors are likely to confuse omniidl.

5.1.1.1  Windows 9x

The output from the C preprocessor is normally fed to the omniidl parser through a pipe. On some Windows 98 machines (but not all!) the pipe does not work, and the preprocessor output is echoed to the screen. When this happens, the omniidl parser sees an empty file, and produces useless stub files with strange long names. To avoid the problem, use the ‘-T’ option to create a temporary file between the two stages.

5.1.2  Forward-declared interfaces

If you have an IDL file like:

then omniidl will normally issue a warning:

  test.idl:1: Warning: Forward declared interface `I' was never
  fully defined

It is illegal to declare such IDL in isolation, but it is valid to define interface I in a separate file. If you have a lot of IDL with this sort of construct, you will drown under the warning messages. Use the -nf option to suppress them.

5.1.3  Comments

By default, omniidl discards comments in the input IDL. However, with the -k and -K options, it preserves the comments for use by the back-ends. The C++ back-end ignores this information, but it is relatively easy to write new back-ends which do make use of comments.

The two different options relate to how comments are attached to declarations within the IDL. Given IDL like:

the -k flag will attach the comment to op1(); the -K flag will attach it to op2().

5.2  C++ back-end options

When you specify the C++ back-end (with -bcxx), the following -Wb options are available. Note that the -Wb options must be specified after the -bcxx option, so omniidl knows which back-end to give the arguments to.

Again, most of these are self-explanatory.

5.2.1  Stub / skeleton files

By default, omniidl separates the normal stub and skeleton file (the SK.cc file) from the ‘dynamic’ stubs (the DynSK.cc file), so applications that do not need support for Any and TypeCode for a particular IDL file do not waste space with unnecessary definitions. It is possible to output both the normal stubs and the dynamic stubs to a single file, by simply specifying the same extension for both files. This command places both the normal stubs and the dynamic stubs in aSK.cc:

omniidl -bcxx -Wba -Wbd=SK.cc a.idl

5.2.2  Module splicing

On ancient C++ compilers without namespace support, IDL modules map to C++ classes, and so cannot be reopened. For some IDL, it is possible to ‘splice’ reopened modules on to the first occurrence of the module, so all module definitions are in a single class. It is possible in this sort of situation:

but not if there are cross-module dependencies:

In both of these cases, the -Wbsplice-modules option causes omniidl to put all of the definitions for module M1 into a single C++ class. For the first case, this will work fine. For the second case, class M1::K will contain a reference to M2::J, which has not yet been defined; the C++ compiler will complain.

5.2.3  Flattened tie classes

Another problem with mapping IDL modules to C++ classes arises with tie templates. The C++ mapping says that for the interface M::I, the C++ tie template class should be named POA_M::I_tie. However, since template classes cannot be declared inside other classes, this naming scheme cannot be used with compilers without namespace support.

The standard solution is to produce ‘flattened’ tie class names, using the -Wbtf command line argument. With that flag, the template class is declared at global scope with the name POA_M_I_tie. i.e. all occurrences of ‘::’ are replaced by ‘_’.

5.2.4  Generating example implementations

If you use the -Wbexample flag, omniidl will generate an example implementation file as well as the stubs and skeletons. For IDL file foo.idl, the example code is written to foo_i.cc. The example file contains class and method declarations for the operations of all interfaces in the IDL file, along with a main() function which creates an instance of each object. You still have to fill in the operation implementations, of course.

5.3  Examples

Generate the C++ headers and stubs for a file a.idl:

omniidl -bcxx a.idl

Generate with Any support:

omniidl -bcxx -Wba a.idl

As above, but also generate Python stubs (assuming omniORBpy is installed):

omniidl -bcxx -Wba -bpython a.idl

Just check the IDL files for validity, generating no output:

omniidl a.idl b.idl

Chapter 6  Interoperable Naming Service

omniORB supports the Interoperable Naming Service (INS). The following is a summary of its facilities.

6.1  Object URIs

As well as accepting IOR-format strings, ORB::string_to_object() also supports two Uniform Resource Identifier (URI) [BLFIM98] formats, which can be used to specify objects in a convenient human-readable form. IOR-format strings are now also considered URIs.

6.1.1  corbaloc

corbaloc URIs allow you to specify object references which can be contacted by IIOP, or found through ORB::resolve_initial_references(). To specify an IIOP object reference, you use a URI of the form:

corbaloc:iiop:<host>:<port>/<object key>

for example:

corbaloc:iiop:myhost.example.com:1234/MyObjectKey

which specifies an object with key ‘MyObjectKey’ within a process running on myhost.example.com listening on port 1234. Object keys containing non-ASCII characters can use the standard URI % escapes:

corbaloc:iiop:myhost.example.com:1234/My%efObjectKey

denotes an object key with the value 239 (hex ef) in the third octet.

The protocol name ‘iiop’ can be abbreviated to the empty string, so the original URI can be written:

corbaloc::myhost.example.com:1234/MyObjectKey

The IANA has assigned port number 2809¹ for use by corbaloc, so if the server is listening on that port, you can leave the port number out. The following two URIs refer to the same object:

corbaloc::myhost.example.com:2809/MyObjectKey
corbaloc::myhost.example.com/MyObjectKey

You can specify an object which is available at more than one location by separating the locations with commas:

corbaloc::myhost.example.com,:localhost:1234/MyObjectKey

Note that you must restate the protocol for each address, hence the ‘:’ before ‘localhost’. It could equally have been written ‘iiop:localhost’.

You can also specify an IIOP version number:

corbaloc::1.2@myhost.example.com/MyObjectKey

Specifying IIOP versions above 1.0 is slightly risky since higher versions make use of various information stored in IORs that is not present in a corbaloc URI. It is generally best to contact initial corbaloc objects with IIOP 1.0, and rely on higher versions for all other object references.

Alternatively, to use resolve_initial_references(), you use a URI of the form:

corbaloc:rir:/NameService

6.1.2  corbaname

corbaname URIs cause string_to_object() to look-up a name in a CORBA Naming service. They are an extension of the corbaloc syntax:

corbaname:<corbaloc location>/<object key>#<stringified name>

for example:

corbaname::myhost/NameService#project/example/echo.obj
corbaname:rir:/NameService#project/example/echo.obj

The object found with the corbaloc-style portion must be of type CosNaming::NamingContext, or something derived from it. If the object key (or rir name) is ‘NameService’, it can be left out:

corbaname::myhost#project/example/echo.obj
corbaname:rir:#project/example/echo.obj

The stringified name portion can also be left out, in which case the URI denotes the CosNaming::NamingContext which would have been used for a look-up:

corbaname::myhost.example.com
corbaname:rir:

The first of these examples is the easiest way of specifying the location of a naming service.

6.2  Configuring resolve_initial_references

The INS specifies two standard command line arguments which provide a portable way of configuring ORB::resolve_initial_references():

6.2.1  ORBInitRef

-ORBInitRef takes an argument of the form <ObjectId>=<ObjectURI>. So, for example, with command line arguments of:

-ORBInitRef NameService=corbaname::myhost.example.com

resolve_initial_references("NameService") will return a reference to the object with key ‘NameService’ available on myhost.example.com, port 2809. Since IOR-format strings are considered URIs, you can also say things like:

-ORBInitRef NameService=IOR:00ff...

6.2.2  ORBDefaultInitRef

-ORBDefaultInitRef provides a prefix string which is used to resolve otherwise unknown names. When resolve_initial_references() is unable to resolve a name which has been specifically configured (with -ORBInitRef), it constructs a string consisting of the default prefix, a ‘/’ character, and the name requested. The string is then fed to string_to_object(). So, for example, with a command line of:

-ORBDefaultInitRef corbaloc::myhost.example.com

a call to resolve_initial_references("MyService") will return the object reference denoted by ‘corbaloc::myhost.example.com/MyService’.

Similarly, a corbaname prefix can be used to cause look-ups in the naming service. Note, however, that since a ‘/’ character is always added to the prefix, it is impossible to specify a look-up in the root context of the naming service—you have to use a sub-context, like:

-ORBDefaultInitRef corbaname::myhost.example.com#services

6.3  omniNames

6.3.1  NamingContextExt

omniNames supports the extended CosNaming::NamingContextExt interface:

to_string() and to_name() convert from CosNaming::Name sequences to flattened strings and vice-versa. Note that calling these operations involves remote calls to the naming service, so they are not particularly efficient. You can use the omniORB specific local omniURI::nameToString() and omniURI::stringToName() functions instead.

A CosNaming::Name is stringified by separating name components with ‘/’ characters. The kind and id fields of each component are separated by ‘.’ characters. If the kind field is empty, the representation has no trailing ‘.’; if the id is empty, the representation starts with a ‘.’ character; if both id and kind are empty, the representation is just a ‘.’. The backslash ‘\’ is used to escape the meaning of ‘/’, ‘.’ and ‘\’ itself.

to_url() takes a corbaloc style address and key string (but without the corbaloc: part), and a stringified name, and returns a corbaname URI (incorrectly called a URL) string, having properly escaped any invalid characters. The specification does not make it clear whether or not the address string should also be escaped by the operation; omniORB does not escape it. For this reason, it is best to avoid calling to_url() if the address part contains escapable characters. omniORB provides the equivalent local function omniURI::addrAndNameToURI().

resolve_str() is equivalent to calling to_name() followed by the inherited resolve() operation. There are no string-based equivalents of the various bind operations.

6.3.2  Use with corbaname

To make it easy to use omniNames with corbaname URIs, it starts with the default port of 2809, and an object key of ‘NameService’ for the root naming context.

6.4  omniMapper

omniMapper is a simple daemon which listens on port 2809 (or any other port), and redirects IIOP requests for configured object keys to associated persistent object references. It can be used to make a naming service (even an old non-INS aware version of omniNames or other ORB’s naming service) appear on port 2809 with the object key ‘NameService’. The same goes for any other service you may wish to specify, such as an interface repository. omniMapper is started with a command line of:

omniMapper [-port <port>] [-config <config file>] [-v]

The -port option allows you to choose a port other than 2809 to listen on. The -config option specifies a location for the configuration file. The default name is /etc/omniMapper.cfg, or C:\omniMapper.cfg on Windows. omniMapper does not normally print anything; the -v option makes it verbose so it prints configuration information and a record of the redirections it makes, to standard output.

The configuration file is very simple. Each line contains a string to be used as an object key, some white space, and an IOR (or any valid URI) that it will redirect that object key to. Comments should be prefixed with a ‘#’ character. For example:

# Example omniMapper.cfg
NameService         IOR:000f...
InterfaceRepository IOR:0100...

omniMapper can either be run on a single machine, in much the same way as omniNames, or it can be run on every machine, with a common configuration file. That way, each machine’s omniORB configuration file could contain the line:

ORBDefaultInitRef corbaloc::localhost

6.5  Creating objects with simple object keys

In normal use, omniORB creates object keys containing various information including POA names and various non-ASCII characters. Since object keys are supposed to be opaque, this is not usually a problem. The INS breaks this opacity and requires servers to create objects with human-friendly keys.

If you wish to make your objects available with human-friendly URIs, there are two options. The first is to use omniMapper as described above, in conjunction with a PERSISTENT POA. The second is to create objects with the required keys yourself. You do this with a special POA with the name ‘omniINSPOA’, acquired from resolve_initial_references(). This POA has the USER_ID and PERSISTENT policies, and the special property that the object keys it creates contain only the object ids given to the POA, and no other data. It is a normal POA in all other respects, so you can activate/deactivate it, create children, and so on, in the usual way.

Children of the omniINSPOA do not inherit its special properties of creating simple object keys. If the omniINSPOA’s policies are not suitable for your application, you cannot create a POA with different policies (such as single threading, for example), and still generate simple object keys. Instead, you can activate a servant in the omniINSPOA that uses location forwarding to redirect requests to objects in a different POA.

1

Not 2089 as printed in [OMG00]!

Chapter 7  Interface Type Checking

This chapter describes the mechanism used by omniORB to ensure type safety when object references are exchanged across the network. This mechanism is handled completely within the ORB. There is no programming interface visible at the application level. However, for the sake of diagnosing the problem when there is a type violation, it is useful to understand the underlying mechanism in order to interpret the error conditions reported by the ORB.

7.1  Introduction

In GIOP/IIOP, an object reference is encoded as an Interoperable Object Reference (IOR) when it is sent across a network connection. The IOR contains a Repository ID (RepoId) and one or more communication profiles. The communication profiles describe where and how the object can be contacted. The RepoId is a string which uniquely identifies the IDL interface of the object.

Unless the ID pragma is specified in the IDL, the ORB generates the RepoId string in the so-called OMG IDL Format¹. For instance, the RepoId for the Echo interface used in the examples of chapter 2 is IDL:Echo:1.0.

When interface inheritance is used in the IDL, the ORB always sends the RepoId of the most derived interface. For example:

In the example, the operation C::op() accepts an object reference of type A. The real type of the reference passed to C::op() is B, which inherits from A. In this case, the RepoId of B, and not that of A, is sent across the network.

The GIOP/IIOP specification allows an ORB to send a null string in the RepoId field of an IOR. It is up to the receiving end to work out the real type of the object. omniORB never sends out null strings as RepoIds, but it may receive null RepoIds from other ORBs. In that case, it will use the mechanism described below to ensure type safety.

7.2  Interface Inheritance

When the ORB receives an IOR of interface type B when it expects the type to be A, it must find out if B inherits from A. When the ORB has no local knowledge of the type B, it must work out the type of B dynamically.

The CORBA specification defines an Interface Repository (IR) from which IDL interfaces can be queried dynamically. In the above situation, the ORB could contact the IR to find out the type of B. However, this approach assumes that an IR is always available and contains the up-to-date information of all the interfaces used in the domain. This assumption may not be valid in many applications.

An alternative is to use the _is_a() operation to work out the actual type of an object. This approach is simpler and more robust than the previous one because no 3rd party is involved, so this is what omniORB does.

The _is_a() operation is part of the CORBA::Object interface and must be implemented by every object. The input argument is a RepoId. The function returns true(1) if the object is really an instance of that type, including if that type is a base type of the most derived type of that object.

In the situation above, the ORB would invoke the _is_a() operation on the object and ask if the object is of type A before it processes any application invocation on the object.

Notice that the _is_a() call is not performed when the IOR is unmarshalled. It is performed just prior to the first application invocation on the object. This leads to some interesting failure modes if B reports that it is not an A. Consider the following example:

If the stubs of A,B,C,D are linked into the executable and:

Case 1

C::op1() and C::op2() return a B. Lines 6–10 complete successfully. The remote object is only contacted at line 7.

Case 2

C::op1() and C::op2() return a D. This condition only occurs if the runtime of the remote end is buggy. Even though the IDL definitions show that D is not derived from A, omniORB gives it the benefit of the doubt, in case it actually has a more derived interface that is derived from both A and D. At line 7, the object is contacted to ask if it is an A. The answer is no, so a CORBA::INV_OBJREF exception is raised. At line 10, the narrow operation will fail, and objA will be set to nil.

If only the stubs of A are linked into the executable and:

Case 1

C::op1() and C::op2() return a B. Lines 6–10 complete successfully. When lines 7 and 10 are executed, the object is contacted to ask if it is an A.

Case 2

C::op1() and C::op2() return a D. This condition only occurs if the runtime of the remote end is buggy. Line 6 completes and no exception is raised. At line 7, the object is contacted to ask if it is an A. If the answer is no, a CORBA::INV_OBJREF exception is raised. At line 10, the narrow operation will fail, and objA will be set to nil.

1

For further details of the repository ID formats, see section 10.6 in the CORBA 2.6 specification.

Chapter 8  Connection and Thread Management

This chapter describes how omniORB manages threads and network connections.

8.1  Background

In CORBA, the ORB is the ‘middleware’ that allows a client to invoke an operation on an object without regard to its implementation or location. In order to invoke an operation on an object, a client needs to ‘bind’ to the object by acquiring its object reference. Such a reference may be obtained as the result of an operation on another object (such as a naming service or factory object) or by conversion from a stringified representation. If the object is in a different address space, the binding process involves the ORB building a proxy object in the client’s address space. The ORB arranges for invocations on the proxy object to be transparently mapped to equivalent invocations on the implementation object.

For the sake of interoperability, CORBA mandates that all ORBs should support IIOP as the means to communicate remote invocations over a TCP/IP connection. IIOP is usually¹ asymmetric with respect to the roles of the parties at the two ends of a connection. At one end is the client which can only initiate remote invocations. At the other end is the server which can only receive remote invocations.

Notice that in CORBA, as in most distributed systems, remote bindings are established implicitly without application intervention. This provides the illusion that all objects are local, a property known as ‘location transparency’. CORBA does not specify when such bindings should be established or how they should be multiplexed over the underlying network connections. Instead, ORBs are free to implement implicit binding by a variety of means.

The rest of this chapter describes how omniORB manages network connections and the programming interface to fine tune the management policy.

8.2  The model

omniORB is designed from the ground up to be fully multi-threaded. The objective is to maximise the degree of concurrency and at the same time eliminate any unnecessary thread overhead. Another objective is to minimise the interference by the activities of other threads on the progress of a remote invocation. In other words, thread ‘cross-talk’ should be minimised within the ORB. To achieve these objectives, the degree of multiplexing at every level is kept to a minimum by default.

Minimising multiplexing works well when the ORB is relatively lightly loaded. However, when the ORB is under heavy load, it can sometimes be beneficial to conserve operating system resources such as threads and network connections by multiplexing at the ORB level. omniORB has various options that control its multiplexing behaviour.

8.3  Client side behaviour

On the client side of a connection, the thread that invokes on a proxy object drives the GIOP protocol directly and blocks on the connection to receive the reply. The first time the client makes a call to a particular address space, the ORB opens a suitable connection to the remote address space (based on the client transport rule as described in section 8.7.1). After the reply has been received, the ORB caches the open network connection, ready for use by another call.

If two (or more) threads in a multi-threaded client attempt to contact the same address space simultaneously, there are two different ways to proceed. The default way is to open another network connection to the server. This means that neither the client or server ORB has to perform any multiplexing on the network connections—multiplexing is performed by the operating system, which has to deal with multiplexing anyway. The second possibility is for the client to multiplex the concurrent requests on a single network connection. This conserves operating system resources (network connections), but means that both the client and server have to deal with multiplexing issues themselves.

In the default one call per connection mode, there is a limit to the number of concurrent connections that are opened, set with the maxGIOPConnectionPerServer parameter. To tell the ORB that it may multiplex calls on a single connection, set the oneCallPerConnection parameter to zero. If the oneCallPerConnection parameter is set to the default value of one, and there are more concurrent calls than specified by maxGIOPConnectionPerServer, calls block waiting for connections to become free.

Note that some server-side ORBs, including omniORB versions before version 4.0, are unable to deal with concurrent calls multiplexed on a single connection, so they serialise the calls. It is usually best to keep to the default mode of opening multiple connections.

8.3.1  Client side timeouts

omniORB can associate a timeout with a call, meaning that if the call takes too long a TRANSIENT exception is thrown. Timeouts can be set for the whole process, for a specific thread, or for a specific object reference.

Timeouts are set using this API:

setClientCallTimeout() sets either the global timeout or the timeout for a specific object reference. setClientThreadCallTimeout() sets the timeout for the calling thread. The calling thread must have an omni_thread associated with it. Setting any timeout value to zero disables it.

Accessing per-thread state is a relatively expensive operation, so per thread timeouts are disabled by default. The supportPerThreadTimeOut parameter must be set true to enable them.

To choose the timeout value to use for a call, the ORB first looks to see if there is a timeout for the object reference, then to the calling thread, and finally to the global timeout.

When a client has no existing connection to communicate with a server, it must open a new connection before performing the call. setClientConnectTimeout() sets an overriding timeout for cases where a new connection must be established. The effect of the connect timeout depends upon whether the connect timeout is greater or less than the timeout that would otherwise be used.

As an example, imagine that the usual call timeout is 10 seconds:

Connect timeout > usual timeout

If the connect timeout is set to 20 seconds, then a call that establishes a new connection will be permitted 20 seconds before it times out. Subsequent calls using the same connection have the normal 10 second timeout. If establishing the connection takes 8 seconds, then the call itself takes 5 seconds, the call succeeds despite having taken 13 seconds in total, longer than the usual timeout.

This kind of configuration is good when connections are slow to be established.

If an object reference has multiple possible endpoints available, and connecting to the first endpoint times out, only that one endpoint will have been tried before an exception is raised. However, once the timeout has occurred, the object reference will switch to use the next endpoint. If the application attempts to make another call, it will use the next endpoint.

Connect timeout < usual timeout

If the connect timeout is set to 2 seconds, the actual network-level connect is only permitted to take 2 seconds. As long as the connection is established in less than 2 seconds, the call can proceed. The 10 second call timeout still applies to the time taken for the whole call (including the connection establishment). So, if establishing the connection takes 1.5 seconds, and the call itself takes 9.5 seconds, the call will time out because although it met the connection timeout, it exceeded the 10 second total call timeout. On the other hand, if establishing the connection takes 3 seconds, the call will fail after only 2 seconds, since only 2 seconds are permitted for the connect.

If an object reference has multiple possible endpoints available, the client will attempt to connect to them in turn, until one succeeds. The connect timeout applies to each connection attempt. So with a connect timeout of 2 seconds, the client will spend up to 2 seconds attempting to connect to the first address and then, if that fails, up to 2 seconds trying the second address, and so on. The 10 second timeout still applies to the call as a whole, so if the total time taken on timed-out connection attempts exceeds 10 seconds, the call will time out.

This kind of configuration is useful where calls may take a long time to complete (so call timeouts are long), but a fast indication of connection failure is required.

8.4  Server side behaviour

The server side has two primary modes of operation: thread per connection and thread pooling. It is able to dynamically transition between the two modes, and it supports a hybrid scheme that behaves mostly like thread pooling, but has the same fast turn-around for sequences of calls as thread per connection.

8.4.1  Thread per connection mode

In thread per connection mode (the default, and the only option in omniORB versions before 4.0), each connection has a single thread dedicated to it. The thread blocks waiting for a request. When it receives one, it unmarshals the arguments, makes the up-call to the application code, marshals the reply, and goes back to watching the connection. There is thus no thread switching along the call chain, meaning the call is very efficient.

As explained above, a client can choose to multiplex multiple concurrent calls on a single connection, so once the server has received the request, and just before it makes the call into application code, it marks the connection as ‘selectable’, meaning that another thread should watch it to see if any other requests arrive. If they do, extra threads are dispatched to handle the concurrent calls. GIOP 1.2 actually allows the argument data for multiple calls to be interleaved on a connection, so the unmarshalling code has to handle that too. As soon as any multiplexing occurs on the connection, the aim of removing thread switching cannot be met, and there is inevitable inefficiency due to thread switching.

The maxServerThreadPerConnection parameter can be set to limit the number of threads that can be allocated to a single connection containing concurrent calls. Setting the parameter to 1 mimics the behaviour of omniORB versions before 4.0, that did not support calls multiplexed on one connection.

8.4.2  Thread pool mode

In thread pool mode, selected by setting the threadPerConnectionPolicy parameter to zero, a single thread watches all incoming connections. When a call arrives on one of them, a thread is chosen from a pool of threads, and set to work unmarshalling the arguments and performing the up-call. There is therefore at least one thread switch for each call.

The thread pool is not pre-initialised. Instead, threads are started on demand, and idle threads are stopped after a period of inactivity. The maximum number of threads that can be started in the pool is set with the maxServerThreadPoolSize parameter. The default is 100.

A common pattern in CORBA applications is for a client to make several calls to a single object in quick succession. To handle this situation most efficiently, the default behaviour is to not return a thread to the pool immediately after a call is finished. Instead, it is set to watch the connection it has just served for a short while, mimicking the behaviour in thread per connection mode. If a new call comes in during the watching period, the call is dispatched without any thread switching, just as in thread per connection mode. Of course, if the server is supporting a very large number of connections (more than the size of the thread pool), this policy can delay a call coming from another connection. If the threadPoolWatchConnection parameter is set to zero, connection watching is disabled and threads return to the pool immediately after finishing a single request.

In the face of multiplexed calls on a single connection, multiple threads from the pool can be dispatched for one connection, just as in thread per connection mode. With threadPoolWatchConnection set to the default value of 1, only the last thread servicing a connection will watch it when it finishes a request. Setting the parameter to a larger number allows the last n connections to watch the connection.

8.4.3  Policy transition

If the server is dealing with a relatively small number of connections, it is most efficient to use thread per connection mode. If the number of connections becomes too large, however, operating system limits on the number of threads may cause a significant slowdown, or even prevent the acceptance of new connections altogether.

To give the most efficient response in all circumstances, omniORB allows a server to start in thread per connection mode, and transition to thread pooling if many connections arrive. This is controlled with the threadPerConnectionUpperLimit and threadPerConnectionLowerLimit parameters. The former must always be larger than the latter. The upper limit chooses the number of connections at which time the ORB transitions to thread pool mode; the lower limit selects the point at which the transition back to thread per connection is made.

For example, setting the upper limit to 50 and the lower limit to 30 would mean that the first 49 connections would receive dedicated threads. The 50th to arrive would trigger thread pooling. All future connections to arrive would make use of threads from the pool. Note that the existing dedicated threads continue to service their connections until the connections are closed. If the number of connections falls below 30, thread per connection is reactivated and new connections receive their own dedicated threads (up to the limit of 50 again). Once again, existing connections in thread pool mode stay in that mode until they are closed.

8.5  Idle connection shutdown

It is wasteful to leave a connection open when it has been left unused for a considerable time. Too many idle connections could block out new connections when it runs out of spare communication channels. For example, most platforms have a limit on the number of file handles a process can open. Many platforms have a very small default limit like 64. The value can often be increased to a maximum of a thousand or more by changing the ‘ulimit’ in the shell.

Every so often, a thread scans all open connections to see which are idle. The scanning period (in seconds) is set with the scanGranularity parameter. The default is 5 seconds.

Outgoing connections (initiated by clients) and incoming connections (initiated by servers) have separate idle timeouts. The timeouts are set with the outConScanPeriod and inConScanPeriod parameters respectively. The values are in seconds, and must be a multiple of the scan granularity.

Beware that setting outConScanPeriod or inConScanPeriod to be equal to (or less than) scanGranularity means that connections are considered candidates for closure immediately after they are opened. That can mean that the connections are closed before any calls have been sent through them. If oneway calls are used, such connection closure can result in silent loss of calls.

8.5.1  Interoperability Considerations

The IIOP specification allows both the client and the server to shutdown a connection unilaterally. When one end is about to shutdown a connection, it should send a CloseConnection message to the other end. It should also make sure that the message will reach the other end before it proceeds to shutdown the connection.

The client should distinguish between an orderly and an abnormal connection shutdown. When a client receives a CloseConnection message before the connection is closed, the condition is an orderly shutdown. If the message is not received, the condition is an abnormal shutdown. In an abnormal shutdown, the ORB should raise a COMM_FAILURE exception whereas in an orderly shutdown, the ORB should not raise an exception and should try to re-establish a new connection transparently.

omniORB implements these semantics completely. However, it is known that some ORBs are not (yet) able to distinguish between an orderly and an abnormal shutdown. Usually this is manifested as the client in these ORBs seeing a COMM_FAILURE occasionally when connected to an omniORB server. The work-around is either to catch the exception in the application code and retry, or to turn off the idle connection shutdown inside the omniORB server.

8.6  Transports and endpoints

omniORB can support multiple network transports. All platforms (usually) have a TCP transport available. Unix platforms support a Unix domain socket transport. Platforms with the OpenSSL library available can support an SSL transport.

Servers must be configured in two ways with regard to transports: the transports and interfaces on which they listen, and the details that are published in IORs for clients to see. Usually the published details will be the same as the listening details, but there are times when it is useful to publish different information.

Details are selected with the endPoint family of parameters. The simplest is plain endPoint, which chooses a transport and interface details, and publishes the information in IORs. Endpoint parameters are in the form of URIs, with a scheme name of ‘giop:’, followed by the transport name. Different transports have different parameters following the transport.

TCP endpoints have the format:

giop:tcp:<host>:<port>

The host must be a valid host name or IP address for the server machine. It determines the network interface on which the server listens. The port selects the TCP port to listen on, which must be unoccupied. Either the host or port, or both can be left empty. If the host is empty, the ORB publishes the IP address of the first non-loopback network interface it can find (or the loopback if that is the only interface), but listens on all network interfaces. If the port is empty, the operating system chooses a port.

Multiple TCP endpoints can be selected, either to specify multiple network interfaces on which to listen, or (less usefully) to select multiple TCP ports on which to listen.

If no endPoint parameters are set, the ORB assumes a single parameter of giop:tcp::, meaning IORs contain the address of the first non-loopback network interface, the ORB listens on all interfaces, and the OS chooses a port number.

SSL endpoints have the same format as TCP ones, except ‘tcp’ is replaced with ‘ssl’. Unix domain socket endpoints have the format:

giop:unix:<filename>

where the filename is the name of the socket within the filesystem. If the filename is left blank, the ORB chooses a name based on the process id and a timestamp.

To listen on an endpoint without publishing it in IORs, specify it with the endPointNoPublish configuration parameter. See below for more details about endpoint publishing.

8.6.1  IPv6

On platforms where it is available, omniORB supports IPv6. On most Unix platforms, IPv6 sockets accept both IPv6 and IPv4 connections, so omniORB’s default giop:tcp:: endpoint accepts both IPv4 and IPv6 connections. On Windows versions before Windows Vista, each socket type only accepts incoming connections of the same type, so an IPv6 socket cannot be used with IPv4 clients. For this reason, the default giop:tcp:: endpoint only listens for IPv4 connections. Since endpoints with a specific host name or address only listen on a single network interface, they are inherently limited to just one protocol family.

To explicitly ask for just IPv4 or just IPv6, an endpoint with the wildcard address for the protocol family should be used. For IPv4, the wildcard address is ‘0.0.0.0’, and for IPv6 it is ‘::’. So, to listen for IPv4 connections on all IPv4 network interfaces, use an endpoint of:

giop:tcp:0.0.0.0:

All IPv6 addresses contain colons, so the address portion in URIs must be contained within [] characters. Therefore, to listen just for IPv6 connections on all IPv6 interfaces, use the somewhat cryptic:

giop:tcp:[::]:

To listen for both IPv4 and IPv6 connections on Windows versions prior to Vista, both endpoints must be explicitly provided.

8.6.1.1  Link local addresses

In IPv6, all network interfaces are assigned a link local address, starting with the digits fe80. The link local address is only valid on the same ‘link’ as the interface, meaning directly connected to the interface, or possibly on the same subnet, depending on how the network is switched. To connect to a server’s link local address, a client has to know which of its network interfaces is on the same link as the server. Since there is no way for omniORB to know which local interface a remote link local address may be connected to, and in extreme circumstances may even end up contacting the wrong server if it picks the wrong interface, link local addresses are not considered valid. Servers do not publish link local addresses in their IORs.

8.6.2  Endpoint publishing

For clients to be able to connect to a server, the server publishes endpoint information in its IORs (Interoperable Object References). Normally, omniORB publishes the first available address for each of the endpoints it is listening on.

The endpoint information to publish is determined by the endPointPublish configuration parameter. It contains a comma-separated list of publish rules. The rules are applied in turn to each of the configured endpoints; if a rule matches an endpoint, it causes one or more endpoints to be published.

The following core rules are supported:

The core rules can be combined using the vertical bar operator to try several rules in turn until one succeeds. e.g:

Multiple rules can be combined using the comma operator to publish more than one endpoint. e.g.

For endpoints with multiple addresses (e.g. TCP endpoints on multi-homed machines), the all() manipulator causes all addresses to be published. e.g.:

A specific endpoint can be published by giving its endpoint URI, even if the server is not listening on that endpoint. e.g.:

If the host or port number for a TCP or SSL URI are missed out, they are filled in with the details from each listening TCP/SSL endpoint. This can be used to publish a different name for a TCP/SSL endpoint that is using an ephemeral port, for example.

omniORB 4.0 supported two options related to endpoint publishing that are superseded by the endPointPublish parameter, and so are now deprecated. Setting endPointPublishAllIFs to 1 is equivalent to setting endPointPublish to ‘all(addr)’. The endPointNoListen parameter is equivalent to adding endpoint URIs to the endPointPublish parameter.

8.7  Connection selection and acceptance

In the face of IORs containing details about multiple different endpoints, clients have to know how to choose the one to use to connect a server. Similarly, servers may wish to restrict which clients can connect to particular transports. This is achieved with transport rules.

8.7.1  Client transport rules

The clientTransportRule parameter is used to filter and prioritise the order in which transports specified in an IOR are tried. Each rule has the form:

<address mask> [action]+

The address mask can be one of

The action is one or more of the following:

The transport-selecting actions form a prioritised list, so an action of ‘unix,ssl,tcp’ means to use a Unix transport if there is one, failing that a SSL transport, failing that a TCP transport. In the absence of any explicit rules, the client uses the implicit rule of ‘* unix,ssl,tcp’.

If more than one rule is specified, they are prioritised in the order they are specified. For example, the configuration file might contain:

  clientTransportRule = 192.168.1.0/255.255.255.0  unix,tcp
  clientTransportRule = 172.16.0.0/255.240.0.0     unix,tcp
                      =       *                    none

This would be useful if there is a fast network (192.168.1.0) which should be used in preference to another network (172.16.0.0), and connections to other networks are not permitted at all.

In general, the result of filtering the endpoint specifications in an IOR with the client transport rule will be a prioritised list of transports and networks. (If the transport rules do not prioritise one endpoint over another, the order the endpoints are listed in the IOR is used.) When trying to contact an object, the ORB tries its possible endpoints in turn, until it finds one with which it can contact the object. Only after it has unsuccessfully tried all permissible endpoints will it raise a TRANSIENT exception to indicate that the connect failed.

8.7.2  Server transport rules

The server transport rules have the same format as client transport rules. Rather than being used to select which of a set of ways to contact a machine, they are used to determine whether or not to accept connections from particular clients. In this example, we only allow connections from our intranet:

  serverTransportRule = localhost                  unix,tcp,ssl
                      = 172.16.0.0/255.240.0.0     tcp,ssl
                      = *                          none

And in this one, we accept only SSL connections if the client is not on the intranet:

  serverTransportRule = localhost