[omniORB] New (undocumented) features in omniORB_2.5.0

[Sai-Lai Lo]

There are two new features in omniORB_2.5.0 which we have not documented in
the user guide. As usual these extensions are part of class omniORB and is
documented in include/omniORB2/omniORB.h

The first feature may be of interest to developers that use omniORB2 with
ObjectStore. The second feature provides support for dynamic object loading.


1. class omniORB::giopServerThreadWrapper
      
   At any time, a single instance of this class (a singleton) is
   registered with the runtime.

   What is the function of this class?
       The runtime uses a number of threads internally to process
       requests from other address spaces. Each thread starts by
       calling the run() method of the singleton. The thread
       will exit when run() returns. The run() method takes two
       arguments: a callback function <fn> and its argument <arg>.
       The run() method *MUST* call fn(arg) to pass the control back
       the runtime at some point. When fn() returns, the run() method
       should cleanup and returns asap.

       Application can modify the behaviour of run() by installing
       another singleton using setGiopServerThreadWrapper(). The
       singleton should be an instance of a derived class of
       giopServerThreadWrapper. The derived class should overload the
       virtual function run() to customise its behaviour.

      For example, to insert the fault handler code for ObjectStore
      a derived class ObjectStoreThreadWrapper is defined as follows:

      class ObjectStoreThreadWrapper : omniORB::giopServerThreadWrapper
      {
       public:
           void run(void (*fn)(void*),void* arg) {
           /* Setup the context to clean up the state attached by
              ObjectStore to this thread */
           OS_PSE_ESTABLISH_FAULT_HANDLER
           fn(arg);
           OS_PSE_END_FAILUT_HANDLER
         }
      }
  
   And in the main()

      omniORB::setgiopServerThreadWrapper(new ObjectStoreThreadWrapper);


2. Dynamic object loading

     An application can register a handler for loading objects            
     dynamically. The handler should have the signature:                  

              omniORB::loader::mapKeyToObject_t                           
                                                                          
     When the ORB cannot locate the target object in this address space,  
     it calls the handler with the object key of the target.              
     The handler is expected to instantiate the object, either in         
     this address space or in another address space, and returns the      
     object reference to the newly instantiated object. The ORB will      
     then reply with a LOCATION_FORWARD message to instruct the client    
     to retry using the object reference returned by the handler.         
     When the handler returns, the ORB assumes ownership of the           
     returned value. It will call CORBA::release() on the returned        
     value when it has finished with it.                                  
                                                                          
     The handler may be called concurrently by multiple threads. Hence it    
     must be thread-safe.                                                 
                                                                          
     If the handler cannot load the target object, it should return       
     CORBA::Object::_nil(). The object will be treated as non-existing.   
                                                                          
     The application registers the handler with the ORB at runtime        
     using omniORB::loader::set(). This function is not thread-safe.      
     Calling this function again will replace the old handler with        
     the new one.                                                         

   class omniORB {
   public:
      ....
     class loader {
     public:
       typedef CORBA::Object_ptr (*mapKeyToObject_t) (
                                        const objectKey& key);

       static void set(mapKeyToObject_t NewKeyToObject);
     };
   };