Features Documentation

This page is not a tutorial on Real-Time CORBA, but is rather a supplement to the specification, covering all implementation-specific details.  Sample code exercising RTCORBA features can be found in $TAO/tests/RTCORBA/.  We hope to have tutorial-style examples available in the near future.

Enabling Real-Time CORBA features

In order to use features from the Real-Time CORBA 1.0 specification in TAO, it must be compiled with both TAO_HAS_RT_CORBA and TAO_HAS_CORBA_MESSAGING set to 1.  These macros are defined in $TAO/tao/orbconf.h  

By default, both Real-Time CORBA and Messaging are enabled in TAO unless Minimum CORBA support is turned on, i.e., TAO_HAS_MINIMUM_CORBA is set to 1.

Migrating from TAO::Client_Priority_Policy

TAO::Client_Priority_Policy is a proprietary policy that was introduced before support for Real-Time CORBA 1.0 was available in TAO.  Since standard RTCORBA policies provide equivalent functionality and more, TAO::Client_Priority_Policy is currently deprecated, and will be completely removed from TAO before the next minor release.  It is disabled by default, but can be enabled manually, although at the expense of making the functionality of standard RTCORBA policies not available.  TAO::Client_Priority_Policy users should migrate to standard RTCORBA policies and mechanisms as follows:

See Threadpools and Priority Policies sections of this document for more information on RTCORBA policies and mechanisms mentioned above.

Priority Mappings

TAO provides two Priority Mappings, Direct and Linear, described below: 

Direct
Maps the first n CORBA priorities to the range of native priorities, where n is the number of native priorities.  The lowest native priority is mapped to CORBA priority 0, next higher native priority is mapped to CORBA priority 1, and so on.  Since in all the operating systems where TAO is supported the native priority set contains less than 32767 priorities, part of the CORBA priority range is left unused.  Consider NT Direct priority mapping as an example.  NT native priorities -15 -2 -1 0 1 2 15 are mapped to CORBA priorities 0 1 2 3 4 5 6, respectively, and the rest of the CORBA priority range is not used.
Linear
Maps each individual native priority to a contiguous range of CORBA priorities, so that the complete CORBA priority range is used up for the mapping.  See $TAO/tao/Strategies/Linear_Priority_Mapping.cpp for more details.

Priority mappings implement the rules for mapping CORBA priority range (from 0 to 32767) into the native OS priority range and vice versa.  However, in some operating systems, the the native OS priority range depends on the scheduling policy being used.  That's why when specifying a priority mapping, scheduling policy must be specified as well.  Below, we describe how to configure TAO to use a particular priority mapping and scheduling policy.  Note, in some operating systems super user privileges are required for use of some of the scheduling policies.

By default TAO uses Direct priority mapping and SCHED_OTHER scheduling policy.  There are two ways for an application to override these settings:

  1. svc.conf file can be used to select a mapping and a scheduling policy the ORB will use.  (This method does not allow the specification of user-defined mappings.)  Config file should contain the following options:

    static Resource_Factory "-ORBPriorityMapping mapping_type -ORBSchedPolicy sched_policy"

    where valid values for mapping_type are linear and direct, and  valid values for sched_policy are SCHED_OTHER, SCHED_FIFO and SCHED_RR.  
  2. TAO::PriorityMappingManager can be used to 1) override the default priority mapping and scheduling policy with another ORB-defined mapping/ scheduling policy combination, 2) install a user-defined priority mapping, 3) obtain a reference to the priority mapping object used by the ORB.  Code excerpts below demonstrate how to perform each of these tasks.

    Obtaining Priority Mapping Manager:
        object = 
                orb->resolve_initial_references ("PriorityMappingManager", ACE_TRY_ENV);
      ACE_TRY_CHECK;
      TAO::PriorityMappingManager_var mapping_manager = 
         TAO::PriorityMappingManager::_narrow (object.in (), ACE_TRY_ENV);
      ACE_TRY_CHECK;
    Overriding priority mapping/policy in effect with another ORB-defined mapping/policy combination:
        #include "tao/Strategies/Linear_Priority_Mapping.h"
      #include "tao/Strategies/Direct_Priority_Mapping.h"
      ...
      RTCORBA::PriorityMapping pm = 
         new TAO_Linear_Priority_Mapping (policy);
                     or 
         new TAO_Direct_Priority_Mapping (policy);  
      mapping_manager->mapping (pm);
      ...
    where policy is SCHED_OTHER, SCHED_FIFO or SCHED_RR.  Priority Mapping Manager takes the ownership of the priority mapping object.   
    Overriding the default with user-defined priority mapping:
        My_Mapping *foo = new My_Mapping;
      mapping_manager->mapping (foo);
    where My_Mapping must inherit from RTCORBA::PriorityMapping (a typedef for TAO_Priority_Mapping class) located in $TAO/tao/Priority_Mapping.h

    Obtaining a pointer to the priority mapping object being used by the ORB:
        RTCORBA::PriorityMapping *pm =
      mapping_manager->mapping ();
    Mapping manager retains the ownership of the priority mapping object.

ORB Default Policies

Real-Time CORBA 1.0 does not specify ORB defaults for the policies it defines, leaving it up to implementations.  Below is a summary TAO defaults.

Policy Default
ServerProtocolPolicy All loaded protocols, in the order they were loaded, with their default properties.  See Protocol Policies section for more details.
ClientProtocolPolicy None
ThreadpoolPolicy Currently none, but will be added once Threadpools are fully supported. 
PriorityModelPolicy Currently none, but will be added once Threadpools are fully supported.
PriorityBandedConnectionPolicy None
PrivateConnectionPolicy None
Priority Mapping Direct mapping with SCHED_OTHER scheduling policy.  See Priority Mappings section for more details.

Threadpools

This feature is still in progress.  Until it is fully supported, follow these steps to obtain threadpool with lane functionality in TAO:

  1. Include "tao/Pool_Per_Endpoint.h" into the server's driver, and substitute the traditional 
         orb->run (ACE_TRY_ENV); 
    with 
         TAO_Pool_Per_Endpoint pool (orb.in (), policy, lane_size, flags);
       pool.run (ACE_TRY_ENV);     
    where policy is SCHED_OTHER, SCHED_FIFO or SCHED_RR, lane_size is the number of threads in each lane, and flags are flags used for thread creation. 
  2. Specify the following in the server's svc.conf: 
    static Advanced_Resource_Factory "-ORBReactorType tp -ORBReactorRegistry per-priority"
  3. Specify endpoint for each lane using the -ORBendpoint command-line option.  For example, for a threadpool with three lanes with priorities 40, 50 and 60, you would specify:
     -ORBendpoint iiop:///priority=40 -ORBendpoint iiop:///priority=50 -ORBendpoint iiop:///priority=60
  4. Do not use RTCORBA::ThreadpoolPolicy

For an example of following the steps above, see $TAO/tests/RTCORBA/Server_Declared.  The limitation of this method is that the threadpool is global, i.e., available to all POAs in the ORB.  There is no way to create additional threadpools and associate them with selected POAs.  Threadpool without lanes functionality is not yet available.

Threadpool threads are the ones doing all the work in the ORB: no additional internal threads are created by the ORB for such tasks as I/O.  

More documentation will be available here once threadpools are fully supported.  Also, see Priority Policies section, which contains information on how threadpools interact with PriorityBandedConnectionPolicy and PriorityModelPolicy.

Priority Policies

The table below lists all possible configurations of policies involving priorities, and summarizes the semantics of each configuration.

Configuration Valid values Semantics 
Threadpool with lanes,
no PriorityModelPolicy,
no PriorityBandedConnectionPolicy		  Invalid Once threadpools are fully supported, there will be an ORB default for  PriorityModelPolicy, i.e., this configuration will not exist.
Threadpool with lanes +
SERVER_DECLARED model,
no PriorityBandedConnectionPolicy		 Server_priority attribute of the PriorityModelPolicy must be equal to the priority of one of the threadpool lanes. (Same goes for priorities of all the objects registered with the target POA) Each object is serviced at its declared priority for the full duration of request, i.e., including I/O and demultiplexing.
Threadpool with lanes + CLIENT_PROPAGATED model, 
no PriorityBandedConnectionPolicy		 Priority of the invoking client thread must be equal to the priority of one of the threadpool lanes. Each object is serviced at  client-propagated priority for the full duration of request, i.e., including I/O and demultiplexing.
Threadpool with lanes +
PriorityBandedConnectionPolicy,
no PriorityModelPolicy		 Invalid Once threadpools are fully supported, there will be an ORB default for  PriorityModelPolicy, i.e., this configuration will not exist.  
Threadpool with lanes +
SERVER_DECLARED model +
PriorityBandedConnectionPolicy		 Server_priority attribute of the PriorityModelPolicy must fall into one of the priority bands. (Same goes for priorities of all the objects registered with the target POA).  In addition, each of the priority bands must cover at least one of the threadpool lane priorities.  Each object is serviced at the priority that falls into the same priority band range as the object's declared priority, for the full duration of request.
Threadpool with lanes +
CLIENT_PROPAGATED model +
PriorityBandedConnectionPolicy		 Priority of the invoking client thread must fall into one of the priority bands.  In addition, each of the priority bands must cover at least one of the threadpool lane priorities. Application request processing takes place at the client-propagated priority.  I/O processing for a request takes place at the priority that falls into the same priority band range as the client-propagated priority.
Threadpool without lanes,
no PriorityModelPolicy,
no PriorityBandedConnectionPolicy		 Invalid Once threadpools are fully supported, there will be an ORB default for  PriorityModelPolicy, i.e., this configuration will not exist.
Threadpool without lanes +
SERVER_DECLARED  model,
no PriorityBandedConnectionPolicy		 All valid CORBA priorities.
(Threadpools without lanes are not yet supported.)		 Request I/O and demultiplexing happen at threadpool priority.  Application level processing is done at declared object priority.
Threadpool without lanes + CLIENT_PROPAGATED model, 
no PriorityBandedConnectionPolicy		 All valid CORBA priorities. 
(Threadpools without lanes are not yet supported.)		 Request I/O and demultiplexing happen at threadpool priority.  Application level processing is done at client-propagated priority.
Threadpool without lanes +
PriorityBandedConnectionPolicy,
no PriorityModelPolicy		 Invalid Once threadpools are fully supported, there will be an ORB default for  PriorityModelPolicy, i.e., this configuration will not exist.
Threadpool without lanes +
SERVER_DECLARED model +
PriorityBandedConnectionPolicy		 Server_priority attribute of the PriorityModelPolicy must fall into one of the priority bands.  (Same goes for priorities of all the objects registered with the target POA).
(Threadpools without lanes not yet supported.)   		 Request I/O and demultiplexing happen at threadpool priority.  Application level processing is done at server-declared object priority.  The only purpose of the PriorityBandedConnectionPolicy is to restrict allowed server-declared  priority values.
Threadpool without lanes +
CLIENT_PROPAGATED model +
PriorityBandedConnectionPolicy		 Priority of the invoking client thread must fall into one of the priority bands.  
(Threadpools without lanes not yet supported.)		 Request I/O and demultiplexing happen at threadpool priority.  Application level processing is done at client-propagated priority.  The sole purpose of the PriorityBandedConnectionPolicy in this configuration is to restrict allowed client-propagated priority values.

Explicit Binding

Object::_validate_connection () method establishes a connection, if one doesn't already exist, and verifies policy overrides for the invoking thread/ its priority/ target object combination.  To establish all connections ahead of time, application must call _validate_connection () for all thread/ priority/ object combinations that will be used.

Protocol Policies

In addition to TCPProtocolProperties defined by the Real-Time CORBA specification, TAO provides configurable properties for each protocol it supports.  Below is a summary of all protocol properties available in TAO.


Real-Time CORBA 1.0 does not define how protocol properties are created.  TAO_Protocol_Factory class can be used to create default ProtocolProperties for a particular protocol given its ProfileId:

class TAO_Protocol_Properties_Factory
{
 public:

   static RTCORBA::ProtocolProperties* 
          create_transport_protocol_property (IOP::ProfileId id);

   static RTCORBA::ProtocolProperties* 
          create_orb_protocol_property (IOP::ProfileId id);
};

Alternatively, concrete ProtocolProperties implementation classes can be instantiated directly as needed. 

The table below summarizes how protocol policies overrides affect protocol selection and configuration in TAO.

Policy ORB default Override levels that have impact on protocol selection Override levels that have impact on protocol configuration
ServerProtocolPolicy All protocols loaded into the ORB, in the order they were loaded. ORB
POA		 ORB 
(If no protocol properties are specified at the ORB level, default protocol configurations are used.)
ClientProtocolPolicy None ORB
Current
Object		 ORB 
(If no protocol properties are specified at the ORB level, default protocol configurations are used.)

NOTE: -ORBSndSock and -ORBRcvSock ORB options have no effect when RTCORBA is enabled.

Protocol policies do not depend on any other Real-Time CORBA features and can be used alone.  In fact, we plan to make protocol policies available outside RTCORBA, and better integrate them with the Pluggable Protocols framework in the near future.

Last Modified: $Date$