## 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, a RT-CORBA client application must link with the RTCORBA library; a RT-CORBA server application must link with the RTCORBA library and the RTPortbaleServer libraries. Since some features in RT-CORBA depend on the messaging specification, all code must be compiled with `TAO_HAS_CORBA_MESSAGING` set to `1`. This 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`.

### Priority Mappings

TAO provides three Priority Mappings: Direct, Linear, and Continuous. If no mapping is specified, Direct Priority Mappings will be used. Note that Continuous was previously referred to as Direct.

Direct
  Maps CORBA priorities directly to native priorities.
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_ROOT/tao/Strategies/Linear_Priority_Mapping.cpp` for more details.
Continuous
  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.

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 RT_ORB_Loader "-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");
   TAO::PriorityMappingManager_var mapping_manager =
   TAO::PriorityMappingManager::_narrow (object.in ());
   `
   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 protocols that are loaded by the ORB by default (e.g., IIOP) and any explicitly specified by the user (e.g., SHMIOP), in the order they were loaded, with their default properties. See Protocol Policies section for more details.
ClientProtocolPolicy | None
ThreadpoolPolicy | None. If no ThreadpoolPolicy policy is specified during POA creation, the default thread-pool will be used for that POA.
PriorityModelPolicy | None
PriorityBandedConnectionPolicy | None
PrivateConnectionPolicy | None
Priority Mapping | Direct mapping with `SCHED_OTHER` scheduling policy. See Priority Mappings section for more details.

### Threadpools

- ThreadPools are now fully supported. Endpoint priorities are no longer supported.

### 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. | None.
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). | All processing is done at the servant's priority.
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. | All processing is done at the client-propagated priority.
Threadpool with lanes + PriorityBandedConnectionPolicy, no PriorityModelPolicy | Invalid. | None.
Threadpool with lanes + `SERVER_DECLARED` model + 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). In addition, each of the priority bands must cover at least one of the threadpool lane priorities. | All processing is done at the servant's priority.
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. | All processing is done at the threadpool lane priority which matches the priority band used by the client.
Threadpool without lanes, no PriorityModelPolicy, no PriorityBandedConnectionPolicy | All valid CORBA priorities. | All processing is done at the threadpool's default priority.
Threadpool without lanes + `SERVER_DECLARED` model, no PriorityBandedConnectionPolicy | All valid CORBA priorities. | Request I/O and demultiplexing processing is done at the threadpool's default priority. Application level processing is done at the servant's priority.
Threadpool without lanes + `CLIENT_PROPAGATED` model, no PriorityBandedConnectionPolicy | All valid CORBA priorities. | Request I/O and demultiplexing processing is done at the threadpool's default priority. Application level processing is done at the client-propagated priority.
Threadpool without lanes + PriorityBandedConnectionPolicy, no PriorityModelPolicy | Invalid. | None.
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). | Request I/O and demultiplexing processing is done at the threadpool's default priority. Application level processing is done at the servant's priority. In this case, PriorityBandedConnectionPolicy is used to restrict the allowed priority values for the servant.
Threadpool without lanes + `CLIENT_PROPAGATED` model + PriorityBandedConnectionPolicy | Priority of the invoking client thread must fall into one of the priority bands. | Request I/O and demultiplexing processing is done at the threadpool's default priority. Application level processing is done at the client-propagated priority. In this case, PriorityBandedConnectionPolicy is used to restrict the allowed priority values for the client.

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

- IIOP
  Protocol ProfileId: 0
  Transport properties interface name: RTCORBA::TCPProtocolProperties (standard)
  Implementation class name: TAO_TCP_Properties

  Protocol Properties Attribute | Default Value
  long send_buffer_size | `ACE_DEFAULT_MAX_SOCKET_BUFSIZ`
  long recv_buffer_size | `ACE_DEFAULT_MAX_SOCKET_BUFSIZ`
  boolean keep_alive (not yet supported) | `1`
  boolean dont_route (not yet supported) | `0`
  boolean no_delay | `1`

- UIOP
  Protocol ProfileId: 0x54414f00U
  Transport properties interface name: RTCORBA::UnixDomainProtocolProperties (TAO-specific)
  Implementation class name: TAO_Unix_Domain_Properties

  Protocol Properties Attribute | Default Value
  long send_buffer_size | `ACE_DEFAULT_MAX_SOCKET_BUFSIZ`
  long recv_buffer_size | `ACE_DEFAULT_MAX_SOCKET_BUFSIZ`

- SHMIOP
  Protocol ProfileId: 0x54414f02U
  Transport properties interface name: RTCORBA::SharedMemoryProtocolProperties (TAO-specific)
  Implementation class name: TAO_SMEM_Properties

  Protocol Properties Attribute | Default Value
  long preallocate_buffer_size | not yet supported
  string mmap_filename | not yet supported
  string mmap_lockname | not yet supported

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: 2001/09/18 00:05:07