## Options for TAO Components

### Table of Contents

- Introduction
- Choosing the Right Approach
- TAO's ORB Configuration Options
  - Environment Variables
  - Command-line Options
    1. Controlling Service Configurator Behavior
    2. Controlling Debugging Information
    3. Optimizing Request Processing
    4. Connection Management and Protocol Selection
    5. Miscellaneous Options
  - Service Configuration File
    1. Simple and Advanced Resource Factories
       1. TAO_Default_Resource_Factory
       2. TAO_Advanced_Resource_Factory
    2. Server_Strategy_Factory
    3. Client_Strategy_Factory

### Introduction

TAO is a highly flexible ORB that contains a wide range of ORB configuration options. One or more of these options can be combined to meet various application requirements, such as low-latency, predictable real-time behavior, or small memory footprint. TAO's ORB configuration options are managed by an object-oriented framework within the ORB Core that contains the following types of entities:

- Settings, which are options that can be assigned values differing from their default settings. Examples include setting the size of a Portable Object Adapter (POA)'s active object map or configuring the ORB to print debugging information as it processes requests. A few of these are run-time options, while a majority of them are compile-time options.

- Resources, which are objects used internally by TAO, such as a reactor framework that demultiplexes new connection and data requests from a client or synchronization mechanisms used to regulate access to certain parts of the ORB.

- Strategies, which are objects that use the Resource entities to perform various ORB tasks, such as connection management, concurrency, and demultiplexing.

- Factories, which TAO uses to create and consolidate its many resources and strategies into a manageable number of factories that can be (re)configured into the ORB conveniently and consistently by ORB and application developers.

The set of TAO ORB configuration options that are represented by the settings, resources, strategies, and factories can be specified via environment variables, service configuration files, and command-line arguments, as outlined below:

- Environment variables are limited to specifying the interoperable object reference (IOR) and port number of TAO's Naming Service, Trading Service and Implementation Repository. They are limited in flexibility and don't provide the most important configuration hooks necessary to configure TAO for real-time and high-performance applications.

- Command-line options are passed to the ORB initialization factory method, `CORBA::ORB_init()`, by an application using the standard argc/argv tuple passed to the application's `main()`. Most of the options that can be exercised through environment variables can also be manipulated through command-line options. Command-line options override the environment variable settings if both are enabled.

- The Service Configurator is a framework that can be used to statically and dynamically configure components into middleware and applications. The information comprising the names of these components and their corresponding options are specified in a service configurator file, whose default file name is `svc.conf`. The service configurator is opened and processed by the ORB in `CORBA::ORB_init()`. The service configurator processing is done after all the command-line options have been parsed.

### Choosing the Right Approach

TAO's command-line options are useful when there's a fixed set of configuration options, each of which has a predefined list of alternative values. Conversely, TAO's service configurator file is useful for configuring a broader range of resources, strategies, and factories. Generally speaking, the service configurator file allows the user to

- configure the existing components (i.e., resources, strategies and factories) based on the predefined list of alternatives that TAO provides or

- extend the existing factories by providing user-defined components and dynamically load them through the service configurator mechanism.

Additionally, the service configurator mechanism allows an application to control the behavior of the ORB using extensible configuration information. In general, the command-line configuration options are provided in TAO in order to leverage preexisting configuration settings that are compiled within the TAO ORB. Users are not allowed to change these settings. In contrast, those options that require more flexible manipulation of resources, strategies, and factories must be configured via service configuration files. As a result, the command-line options and the service configurator options cannot be used interchangeably.

### TAO's ORB Configuration Options

This section provides a detailed overview of how to configure TAO's options using environment variables, command-line options, and service configuration files.

### Environment Variables

As mentioned earlier, environment variables have a limited use in TAO ORB configuration. The currently supported environment variables are listed below. They are used to specify the IOR and port numbers for three of TAO's ORB services.

> Environment Variable | Description
> --- | ---
> `NameServicePort` which | Specifies which port the Naming Service is listening on for multicast requests.
> `TradingServicePort` which | Specifies which port the Trading Service is listening on for multicast requests.
> `ImplRepoServicePort` which | Specifies which port the Implementation Repository is listening on for multicast requests.

In addition to being able to define the port where these known services are listening for multicast requests, as above, it is possible to set an environment variable that specifies the IOR of any named service. For example `NameServiceIOR=<which>,TradingServiceIOR=<which>, ImplRepoServiceIOR=<which>, MyServiceIOR=<which>`. This will have a similar effect to defining an -ORBInitRef value on the command line (see below). Any value set as a command line -ORBInitRef option will override any value set as an environment variable for the same service name.
In general, setting environment variables is not particularly portable or convenient, which is why users can also set these options via command-line options. The example shown below demonstrates a deployment scenario where the client and Naming Service run on the same host:

`% NameService.exe -ORBEndpoint iiop://localhost:12345`

`% client.exe -ORBInitRef NameService=corbaloc:iiop:localhost:12345/NameService`

An explanation of these command-line options appears below.

### Command-line Options

TAO's run-time behavior can also be controlled by passing options via the CORBA initialization method `CORBA::ORB_init()`. ORB initialization options are commonly passed into the program from the command-line, using the `argc` and `argv` parameters available to the `main()` function.

Command-line options can be classified into the following groups according to their purposes:

1. Controlling Service Configurator Behavior
2. Controlling Debugging Information
3. Optimizing Request Processing
4. Connection Management and Protocol Selection
5. Miscellaneous Options

We describe each of these five groups of options below.

#### 1. Controlling Service Configurator Behavior

The options described below influence the behavior of the ORB's service configurator, which is opened and processed after the command-line options have been parsed.

> Option | Description
> --- | ---
> `-ORBSvcConf` config filename | Specifies the name of the file used to read service configuration directives via the Service Configurator framework. By default, a service configurator-based application will look for a file named `"svc.conf"` in the current directory.
> `-ORBSvcConfDirective` directivestring | Specifies a service configuration directive, which is passed to the Service Configurator. You can pass multiple of these options on the same command-line.
> `-ORBServiceConfigLoggerKey` logger key | Set the logger key in the `ACE_Service_Config` framework. Equivalent to the `-k` option on the ACE service configurator class.
> `-ORBSkipServiceConfigOpen` | Do not process any `svc.conf` files, which has the side-effect of not initializing the ACE Service Configurator framework or registering the SIGHUP signal.
> `-ORBIgnoreDefaultSvcConfFile` | Do not process default `svc.conf` file. This does not prohibit processing of explicitly provided `-ORBSvcConf` and/or `-ORBSvcConfDirective` options.
> `-ORBGestalt Local|ORB:orbid` | Instruct the ORB to create a local configuration "gestalt" or context. By default, all ORBs share a common configuration context. This is defined by a Service Repository that contains service objects, such as the resource factory. In some cases multiple ORBs may be dynamically loaded and as such may wish to have distinct configurations. Passing the `Local` argument achieves this. Service objects loaded by an ORB with a local configuration context will be used by that ORB in place of any default service object. The final variation is that of shared contexts. Passing the argument `ORB:orbid` will cause the ORB to share the local configuration of another ORB as identified with the supplied id. The shared context feature is not yet implemented.

#### 2. Controlling Debugging Information

During application development and testing, it is often necessary to control the amount and type of debugging information output by the ORB. The following options enable TAO to provide debugging information at several levels of granularity.

> Option | Description
> --- | ---
> `-ORBDebug` | Instructs the ORB to print debugging messages from the service configurator framework. This option does not have a value but is used as a toggle to enable or disable debugging messages.
> `-ORBDebugLevel` level | Control the level of debugging in the ORB. Higher numbers generate more output (try 10). The default value of this option is 0.
> `-ORBVerboseLogging` level (0|1|2) | Controls the amount of status data printed on each line of the debug log. Higher numbers generate more output. The default value of this option is 0.
> `-ORBLogFile` Logfilename | Causes all `ACE_DEBUG` and `ACE_ERROR` output to be redirected to the designated `Logfilename`.
> `-ORBHandleLoggingStrategyEvents` LoggingStrategyServiceName | Causes use of ORB reactor for dispatching timer events to ACE_Logging_Strategy configured as a dynamic service with name `LoggingStrategyServiceName`. This allows to implement log file rotation.
> `-ORBObjRefStyle` IOR/URL | Specifies the user-visible style of object references. The `IOR` style (default) is the conventional CORBA object reference, whereas the `URL` style looks more like a URL.

#### 3. Optimizing Request Processing

It is often possible to increase TAO's throughput and reduce latency by optimizing certain stages of request processing in the ORB. The following command-line options control various optimizations during request processing.

> Option | Description
> --- | ---
> `-ORBCDRTradeoff` maxsize | Control the strategy to tradeoff between copy vs. no copy marshaling of octet sequences. If an octet sequence is smaller than `maxsize` (which defaults to `ACE_DEFAULT_CDR_MEMORY_TRADEOFF`) -- and the current message block contains enough space for it -- the octet sequence is copied instead of appended to the CDR stream.
> `-ORBMaxMessageSize` maxsize | Set maximum size of outgoing GIOP request/reply. The request or reply being sent will be fragmented, if necessary.
> `-ORBCollocation` global/per-orb/no | Specifies the use of collocation object optimization. If `global` is specified (default), objects in the same process will be treated as collocated. If `per-orb` is specified, only objects in the same ORB are treated as collocated. When no is specified, no objects are treated as collocated.
> `-ORBCollocationStrategy` thru_poa/direct | Specifies what type of collocated object to use. If the `thru_poa` (default) strategy is used, TAO uses the collocation object implementation that respects POA's current state and policies. When using the `direct` strategy, method invocations on collocated objects become direct calls to servant without checking POA's status, which can increase performance. If you use the `direct` strategy, your interfaces must be compiled with the `-Gd` IDL compiler option.
> `-ORBAMICollocation` 1|0 | Specifies what happens when making collocated AMI invocations. When 1 (default) an AMI call will be done on a collocated servant and the client thread will be used to invoke the servant, when 0 the collocated call will be converted to a remote call so that a different thread could be used to execute the servant.
> `-ORBNodelay` boolean (0|1) | Enable or disable the `TCP_NODELAY` option (Nagle's algorithm). By default, `TCP_NODELAY` is enabled.
> `-ORBRcvSock` receive buffer size | Specify the size of the socket receive buffer as a positive, non-zero integer. If not specified, the `ACE_DEFAULT_MAX_SOCKET_BUFSIZ` default is used.
> `-ORBSndSock` send buffer size | Specify the size of the socket send buffer as a positive, non-zero integer. If not specified, the `ACE_DEFAULT_MAX_SOCKET_BUFSIZ` default is used.
> `-ORBStdProfileComponents` boolean (0|1) | If 0 then the ORB does not generate the OMG standardized profile components, such as the ORB type and code sets. Notice that the presence of this components is optional in GIOP 1.1 The default value is controlled by a compile-time flag defined in `orbconf.h`.
> `-ORBNegotiateCodesets` boolean (0|1) | If 0 then the ORB does not include the codeset negotiation subsystem, TAO_Codeset. This yields a somewhat smaller runtime footprint as well as a smaller IOR. However this also removes the ability to interoperate with ORBs on systems using alternative character or wide charater encodings. The default value may be set at compile time by defining `TAO_NEGOTIATE_CODESETS 0` in `orbconf.h`. Codeset negotiation support is enabled by default in TAO as shipped. Note to static lib users In order to build TAO statically and get the codeset negotiation feature, two additional steps are needed to ensure the TAO_Codeset library is linked in and initalized. Add the MPC feature "negotiate_codesets=1" to the default.features file and regenerate your makefiles, and add `#include "tao/Codeset/Codeset.h"` somewhere in your application source, such as the cpp file containing your main.
> `-ORBSingleReadOptimization` boolean (0|1) | This option controls whether TAO's ``single read optimization'' is used when receiving requests. If this option is disabled (`0`), the ORB will do two reads to read a request: one reads the request header and the other reads the request payload. If this option is enabled (`1`), the ORB will do a read of size `TAO_MAXBUFSIZE`, hoping to read the entire request. If more than one request is read they will be queued up for processing later. This option defaults to `1` because it can provide better performance. In the case of Real-time CORBA, however, this option should be set to `0`. Consider the following scenario: (1) two requests are read from one socket, (2) the additional request is queued, and (3) the ORB uses its Reactor's notification mechanism to wake up the follower threads. If at the same time, however, new requests arrive on others sockets of higher priority the lower priority queued message will be processed before the newly arrived higher priority request since Reactor notifications are given preferences over normal I/O, thereby causing priority inversion.
> `-ORBDisableRTCollocation` boolean (0|1) | This option controls whether the application wants to use or discard RT collocation decisions made by the RT ORB. A value of `1` (true) disables RT collocation decisions and falls back on the default collocation decisions implemented in the default ORB, which is useful for applications using the RT ORB and doesn't want to use the RT collocation decisions but fallback on the default decisions for better performance. The default value is `0` (false).
> `-ORBUseLocalMemoryPool` boolean (0|1) | TAO can use a local memory pool to satisfy some of its needs for heap storage, as it is often more efficient than using the platform's default memory allocator. The local pool will always grow as large as necessary to satisfy memory allocations, but it will never shrink. This means that sometimes a process can retain memory that it no longer needs. If the default allocator is used then TAO gives memory back as soon as it is not needed which allows for better resource sharing at the expense of memory deallocation time. If this option is disabled (`0`), the ORB will use the default allocator for the platform. If this option is enabled (`1`), the orb will use the local memory pool. This option defaults to the compile-time option specified by `TAO_USES_LOCAL_MEMORY_POOL`.

#### 4. Connection Management and Protocol Selection

TAO can send and receive requests and replies using various transport protocols. Each protocol has its own concept of an endpoint. The following options manage connections and control protocol selection within a TAO application.

> Option | Description
> --- | ---
> `-ORBAcceptErrorDelay` seconds | This argument controls the amount of time to wait before attempting to accept new connections in the event that a transient error occurs (such as running out of file handles). A delay of zero indicates that accepting should not be attempted again after the transient error and the handler will be removed from the reactor.
> `-ORBDefaultInitRef` IOR prefix | This argument allows resolution of initial references not explicitly specified with `-ORBInitRef`. It requires a URL prefix that, after appending a slash '/' ('|' for the UIOP pluggable protocol) and a simple object key, forms a new URL to identify an initial object reference. The URL prefix format currently supported is based on the standard `corbaloc` mechanism in the CORBA Interoperable Naming Service.
> `-ORBDottedDecimalAddresses` boolean (0|1) | Use the dotted decimal notation for addresses. This option can be used to workaround broken DNS implementations and may also reduce the time spent resolving IP addresses. This option is enabled (`1`) by default on Windows since DNS is often misconfigured there. On other platforms this option is disabled (`0`) since domain names are more flexible address notations for IORs.
> `-ORBNoServerSideNameLookups` boolean (0|1) | Setting this to 1 will prevent the ORB from looking up the peer's hostname when accepting an incoming connection from a client when the above value (`ORBDottedDecimalAddresses`) is `0`. This option is disabled (`0`) by default.
> `-ORBEndpoint` endpoint | This option is same as the `-ORBListenEndPoints` option described below. This option will be deprecated in later versions on TAO since the CORBA specification now defines the `-ORBListenEndpoints` option instead.
> `-ORBPreferredInterfaces` "targetNetwork:localNetwork,.." | This option allows clients running on a multihomed host to pick a local network/interface to communicate with a remote target. When TAO attempts to establish a connection with a host matching targetNetwork, then it will use the local ip address matching localNetwork. Simple wildcards can be used for both parameters, and multiple preferred interfaces can be specified using comma separators. For example, for a machine with two network cards identified by the ip addresses 192.168.1.10 and 192.168.1.20, you can use -ORBPreferredInterfaces *=*10,*=*20. Or to force all communication on the loopback address to try to first use the loopback address, use -ORBPreferredInterfaces 127.0.0.1=127* . targetNetwork can use any string, and must typically match with the value read from an IOR. localNetwork must use a dotted decimal address, because it will be matched with the local ip interfaces.
> `-ORBEnforcePreferredInterfaces` boolean (0|1) | If this option is set to `1` (true), then TAO will only try to use the interfaces specified by the `-ORBPreferredInterfaces` option. The default is `0` (false), in which case if a connection cannot be made using a preferred interface, TAO will attempt to use the default interface (`INADDR_ANY`). Note: If none of the preferred interfaces apply to an outgoing connection then they will not be enforced. For this option to have any effect, therefore, the connection through a legal preferred interface must fail.
> `-ORBKeepalive` boolean (0|1) | This option allows users to specify that the SO_KEEPALIVE option is set on TCP sockets used by IIOP. The default is `0` (false).
> `-ORBDontRoute` boolean (0|1) | This option allows users to specify that the SO_DONTROUTE option is set on TCP sockets used by IIOP. The default is `0` (false).
> `-ORBLingerTimeout` timeout | This option allows users to set the linger timeout on a TCP socket before closing it. Hence, this option is only useful when using IIOP. The `timeout` value can be in the range of zero to the maximum signed integer value for the particular platform on which TAO is running.
> `-ORBIPHopLimit` hops | This option allows users to specify the TTL (IPv4) or hop limit (IPv6) value used when datagrams are sent over a socket. The default is the one selected by the Operating System. The `hops` value can be in the range of zero to the maximum signed integer value for the particular platform on which TAO is running. Currently this feature works in IIOP, DIOP, SCIOP, and MIOP.
> `-ORBIPMulticastLoop` boolean (0|1) | This option allows users to specify that the IP_MULTICAST_LOOP / IPV6_MULTICAST_LOOP option is set on multicast sockets. The default is `1` (true).
> `-ORBListenEndpoints` endpoint | This option was introduced with the CORBA Object Reference Template (ORT) specification. It instructs a server ORB to listen for requests on the interface specified by `endpoint`. When used with Real-time CORBA, the option specifies the endpoints that the default thread pool listens to. TAO endpoints are specified using a URL style format. An endpoint has the form: `protocol://V.v@addr1,...,W.w@addrN` where `V.v` and `W.w` are optional protocol versions for each address. An example of an IIOP endpoint is: `iiop://hostname:port` Sets of endpoints may be specified using multiple `-ORBListenEndpoints` options or by delimiting endpoints with a semi-colon (;). For example, `-ORBListenEndpoints iiop://localhost:9999 -ORBListenEndpoints uiop:///tmp/mylocalsock -ORBListenEndpoints shmiop://10002` is equivalent to: `-ORBListenEndpoints 'iiop://localhost:9999;uiop:///tmp/mylocalsock;shmiop://10002'` Notice the single quotes (') in the latter option specification. Single quotes are needed to prevent the shell from interpreting text after the semi-colon as another command to run. If an endpoint is specified without an `addr` such as the following: `-ORBListenEndpoints uiop:// -ORBListenEndpoints shmiop://` then a default endpoint will be created for the specified protocol. Click here for much more on how to specify endpoints.
> `-ORBLaneEndpoint` endpoint | This option is same as the `-ORBLaneListenEndPoints` option described below. This option will be deprecated in later versions on TAO.
> `-ORBLaneListenEndpoints` thread-pool-id:thread-lane-id endpoint | This option allows the user to specify endpoints for thread pools and lanes. This option is only meaningful when used with Real-time CORBA and only makes sense when the thread pools and lanes are created in the same order across server incarnations. See `-ORBListenEndPoints` option on how to specify endpoints. An example is: `2:3 iiop://localhost:2345` where `2` specifies the second thread pool created by the process and `3` specifies the third lane of that thread pool. Note that `0` should be used for the lane when specifying endpoints for thread pools without lanes. `*:*` can be used to specify all pools and lanes, `1:*` means all lanes from pool `1`, and `*:1` means lane `1` from all pools. Sets of endpoints may be specified using multiple `-ORBLaneListenEndpoints` options or by delimiting endpoints with a semi-colon (;). For example, `-ORBLaneListenEndpoints 1:4 iiop://localhost:9999 -ORBLaneListenEndpoints 1:4 uiop:///tmp/mylocalsock -ORBLaneListenEndpoints 1:4 shmiop://10002` is equivalent to: `-ORBLaneListenEndpoints 1:4 'iiop://localhost:9999;uiop:///tmp/mylocalsock;shmiop://10002'` Notice the single quotes (') in the latter option specification. Single quotes are needed to prevent the shell from interpreting text after the semi-colon as another command to run. If an endpoint is specified without an `addr` such as the following: `-ORBLaneListenEndpoints 2:3 uiop:// -ORBLaneListenEndpoints 2:3 shmiop://` then a default endpoint will be created for the specified protocol.
> `-ORBImplRepoServicePort` portspec | Specifies which port the Implementation Repository is listening on for multicast requests. By default, the `TAO_DEFAULT_IMPLREPO_SERVER_REQUEST_PORT` (10018) is used.
> `-ORBInitRef` ObjectId=IOR | Allows specification of an arbitrary object reference for an initial service. The IOR could be in any one of the following formats: OMG `IOR`, `URL`, `corbaloc` (including `uioploc`) or `file`. `corbaloc` is a multiple end-point IOR understood by `ORB::string_to_object()` and used as a boot-strapping mechanism by the `ORB::resolve_initial_references()`. The mappings specified through this argument override the ORB install-time defaults. The `file://pathname` interprets the contents of the `pathname` file as an object reference in any of the above formats.
> `-ORBMulticastDiscoveryEndpoint` endpoint | Specifies the `endpoint` that should be used for locating the Naming Service through multicast. endpoint is of the form `ip-number:port-number` (e.g., `"tango.cs.wustl.edu:1234"` or `"128.252.166.57:1234"`). If there is no `':'` in the end_point it is assumed to be a port number, with the IP address being `INADDR_ANY`.
> `-ORBNameServicePort` portspec | Specifies which port the Naming Service is listening on for multicast requests. By default, the `TAO_DEFAULT_NAME_SERVICE_REQUEST_PORT` (10013) value is used.
> `-ORBTradingServicePort` portspec | Specifies to which port the Trading Service is listening on for multicast requests. By default, the `TAO_DEFAULT_TRADING_SERVICE_REQUEST_PORT` (10016) value is used.
> `-ORBUseIMR` boolean (0|1) | This argument specifies that for POAs with the `PERSISTENT` policy, that the TAO Implementation Repository should be used for notification of startup and shutdown and object references should be changed to use the Implementation Repository also (N.B. although see `-ORBIMREndpointsInIOR` below).
> `-ORBIMREndpointsInIOR` boolean (0|1) | This argument specifies whether, for POAs with the `PERSISTENT` policy, the TAO Implementation Repository listen endpoints should be encoded into IORs when `-ORBUseIMR` is set. The default is true.
> `-ORBUseParallelConnects` boolean (0|1) | This option allows users to specify the ORB attempt to connect simultaniously to all endpoints listed in profiles, rather than stepping through individual endpoints, trying and possibly failing, before moving on to the next. For this feature to work, the server must be using shared profiles. The default is `0` (false).
> `-ORBUseSharedProfile` boolean (0|1) | This option allows multiple implicit or explicit endpoints to be combined into a single profile for a given protocol rather than using multiple profiles. For IIOP in non RTCORBA environments, the CORBA specified tagged component `TAG_ALTERNATE_IIOP_ADDRESS` is used to encode the combined endpoints. Processses using RTCORBA and priority banded connections will continue to generate Profiles with `TAO_TAG_IIOP_ENDPOINT` components. This options is disabled by default.
> `-ORBParallelConnectDelay` unsigned long msec | When using parallel connection attempts, this option defines the number of milliseconds to delay when polling previously started connection attempts. If a server is likely to be busy, this client side option will help avoid creating redundant connections that must be accepted, only to be closed a moment later. However, if the first reachable endpoint is far down the list, this option will increase the delay before that endpoint is reached. The default is `0`.
> `-ORBPreferIPV6Interfaces` boolean (0|1) | If option is `1` (true) it directs the default endpoint selector for client connections to first attempt to connect any IIOP endpoints from a provided IOR specifying IPv6 interfaces. Only when none of these can be found or sucessfully connected IPv4 interfaces will be tried. The default is `0` (false). This option is only available for IPv6 enabled builds of TAO (`ACE_HAS_IPV6`).
> `-ORBConnectIPV6Only` boolean (0|1) | If this option is `1` (true) it directs a server ORB to: allow only IPv6 interfaces as listening endpoints encode only IPv6 interfaces in the IOR profile prevent (depending on availability of IPV6_V6ONLY socket option) or block IPv6 to IPv4 connections This option directs the default endpoint selector for client connections to only attempt to connect any IIOP endpoints from a provided IOR specifying IPv6 interfaces. Any available IPv4 interfaces will be ignored. The default setting is `0` (false). This option is only available for IPv6 enabled builds of TAO (ACE_HAS_IPV6).
> `-ORBUseIPV6LinkLocal` boolean (0|1) | If this option is `1` (true) it directs a server ORB to allow connections on IPv6 link local addresses. The default setting is `0` (false). This option is only available for IPv6 enabled builds of TAO (ACE_HAS_IPV6).

#### 5. Miscellaneous Options

Options in this category don't control the behavior of the ORB in terms of resouces or strategies. Instead, they are helper options provided for specific application requirements.

> Option | Description
> --- | ---
> `-ORBId` orb_name | This option allows the name of an ORB to be set to `orb_name`. The `ORBId` will be passed to the `CORBA::ORB_init()` method to differentiate coexisting ORBs (when there is more than one ORB).
> `-ORBServerId` server_id | This option allows setting a name/id to a server to uniquely identify a server to TAO's Implementation Repository.
> `-ORBDaemon` | Specifies that the ORB should daemonize itself, i.e., run as a background process. Note, that this changes the working directory to be the root directory "/". This especially affects relative paths specified at the command line. This option is only meaningful on OS platforms that support daemonization.
> `-ORBForwardInvocationOnObjectNotExist` boolean (0|1) | If this option is 1, the ORB forwards the request to next available profile when receiving OBJECT_NOT_EXIST exception reply. The default value is `0` which means the request is not forwarded upon OBJECT_NOT_EXIST exception.
> `-ORBForwardOnceOnObjectNotExist` boolean (0|1) | If this option is 1, the ORB forwards the request if it receives OBJECT_NOT_EXIST exception reply. If it receives one of the exceptions (OBJECT_NOT_EXIST, COMM_FAILURE, TRANSIENT, INV_OBJREF) during forwarding, the request is not forwarded again and exception is propagated to the client code. The default value is `0` which means the request is not forwarded upon OBJECT_NOT_EXIST exception.
> `-ORBForwardOnceOnCommFailure` boolean (0|1) | If this option is 1, the ORB forwards the request if it receives COMM_FAILURE exception reply. If it receives one of the exceptions (OBJECT_NOT_EXIST, COMM_FAILURE, TRANSIENT, INV_OBJREF) during forwarding, the request is not forwarded again and exception is propagated to the client code. The default value is `0` which means the request is not forwarded upon COMM_FAILURE exception.
> `-ORBForwardOnceOnTransient` boolean (0|1) | If this option is 1, the ORB forwards the request if it receives TRANSIENT exception reply. If it receives one of the exceptions (OBJECT_NOT_EXIST, COMM_FAILURE, TRANSIENT, INV_OBJREF) during forwarding, the request is not forwarded again and exception is propagated to the client code. The default value is `0` which means the request is not forwarded upon TRANSIENT exception.
> `-ORBForwardOnceOnInvObjref` boolean (0|1) | If this option is 1, the ORB forwards the request if it receives INV_OBJREF exception reply. If it receives one of the exceptions (OBJECT_NOT_EXIST, COMM_FAILURE, TRANSIENT, INV_OBJREF) during forwarding, the request is not forwarded again and exception is propagated to the client code. The default value is `0` which means the request is not forwarded upon INV_OBJREF exception.

### The Service Configurator File

Internally, TAO uses the ACE Service Configurator framework to allow applications to configure the ORB at run-time. Applications provide a file named `svc.conf` with options that configure appropriate strategies in to the ORB. The options enable developers to control the behavior of the factories, strategies, and resources that the ORB uses. By default, TAO provides the following set of factories:

1. Default Resource and Advanced Resource Factories. This factory controls the creation of configurable resources used by TAO's ORB core. The resource factory is responsible for constructing and providing access to various resources used by the ORB irrespective of whether they perform client or server roles. ORB resources include reactors, protocol factories, message flushing strategies, connection purging strategies and different IOR parsers.

2. Server Strategy Factory. This factory creates various strategies of special utility to the ORB that is useful for controlling the behavior of servers. This factory is responsible for creating strategies useful for server objects like the concurrency strategy and the request demultiplexing strategies used by the POA.

3. Client Strategy Factory. This factory creates various strategies of special utility to the ORB, useful for controlling the behavior of clients. This factory is responsible for creating strategies useful for clients such as request multiplexing strategies, wait strategies, connect strategies etc.

Options specified via a `svc.conf` file can represent either the components provided by TAO (including the `Resource_Factory`, and the `Server_Strategy_Factory` and `Client_Strategy_Factory`) or customized components developed by the users. The service configurator file (`svc.conf`) provided by the user identifies the components to be loaded with the required strategies for each component.

A `svc.conf` file is not required to run TAO applications since TAO provides a set of default values for strategies useful for the most common use cases, i.e., the default values are set for all options. When a TAO application calls `CORBA::ORB_init()` it will try to find the `svc.conf` file. If found, TAO will parse and process the directives in the file; if not found, the default value for the default components will be used.

#### 1. Default and Advanced Resource Factories

Many of TAO's ORB Core resources are fixed, including the allocators for the incoming and outgoing data paths, and data structures for the various maps and lists maintained by the ORB. There is some flexibility, however, in the choice of a reactor, the selection of transport protocols, choice of data flushing strategy, various forms of connection resource management strategies and possibility of using different IOR parsers. The resource factories supported by TAO include the `Resource_Factory` and `Advanced_Resource_Factory`. TAO provides defaults of these factories, as well as the specialized resource factories described below:

> Resource Factory | Description
> --- | ---
> `Resource Factory` | Unless configured otherwise, this is the default resource factory used by the ORB.The resource factory is responsible for creating and providing access to various resources used by the server and client ORBs. The resources managed by this factory include creation of acceptor and connector registries, choice of data flushing strategy, limits for connection resource management, types of CDR buffers used for marshalling and demarshalling data, and different IOR parsers.
> `Advanced Resource Factory` | This factory provides more advanced configuration options in the addition to all the features of the default resource factory. The advanced resource factory gives more control than the default resource factory over the type of resources used and how those resources are accessed. In addition to the options provided by the default resource factory, the advanced resource factory provides options that allow selecting different reactors, choosing different transport mechanisms and selecting the right connection purging strategy to maintain limits on resources used. The advanced resource factory was created to allow more advanced options while keeping the footprint of the default resource factory small. The advanced resource factory inherits from the default resource factory and accepts all of its options in addition to its own.
> `Qt Resource Factory` | This is a specialized resource factory providing the means for integrating with the Qt GUI toolkit from Trolltech.
> `Xt Resource Factory` | This is a specialized resource factory providing the means for integrating with the X Window System's Xt Intrinsics toolkit.

#### 1.1. Resource_Factory

Typically, the above options are exercised via the service configurator (svc.conf) file. The following line in the `svc.conf` file (all in one line)

`static Resource_Factory "[list of options]"`

will load the default resource factory with the options listed within the double quotes. The following table shows the list of possible options that can be specified within the double quotes in the above directive. There is an example of how this is used in TAO.

> Option | Description
> --- | ---
> `-ORBReactorMaskSignals` 0/1 | ACE select reactors mask signals during upcalls to the event handlers. This is only useful if the application is going to trap those signals and handle them in any special way. Disabling the mask can improve performance by reducing the number of kernel level locks.
> `-ORBProtocolFactory` factory | Specify which pluggable protocol factory to load. By default, only the factory for the IIOP protocol (`IIOP_Factory`) is loaded. For example, if some protocol called `Foo` whose factory was called `Foo_Factory` was available, then it could be loaded into TAO by specifying `-ORBProtocolFactory Foo_Factory` in the service configurator file. The `Foo` pluggable protocol would then be available for use.
> `-ORBIORParser` parser | Name an IOR Parser to load. IOR Parsers are used to interpret strings passed to `ORB::string_to_object()`. By default the ORB can handle multiple string formats, including `IOR:`, `corbaloc:`, `corbaname:`, and `file:`. The application developer can add new IOR formats using this option.
> `-ORBConnectionPurgingStrategy` type | Opened connections are added to the transport cache so they can be reused. If a process continues to run and these connections are not reused, however, the cache will continue to grow. Before each new connection, therefore, the cache is checked and purged if it has reached the limit specified by the `-ORBConnectionCacheMax` option or the system default if that option was not used. The possible values for type are `lru`, `lfu`, `fifo`, and `null`. The default is `lru` (least recently used). The other options are `lfu` (least frequently used), `fifo` (first in first out), and `null` (no connections are purged) and are contained within the TAO Strategies library.
> `-ORBConnectionCacheMax` limit | The transport cache will grow to a maximum of the specified limit. The default is system dependent, but can be overridden at compile-time by defining the preprocessor macro `TAO_CONNECTION_CACHE_MAXIMUM`.
> `-ORBMuxedConnectionMax` number | The transport cache allows only specified number of connections-per-QoS property to be added to connection cache. Threads not getting the connections will wait for the connections to be released. This option is more useful for transports using a muxed connection strategy and want control over the number of connections that are created by the active threads.
> `-ORBConnectionCachePurgePercentage` percent | If the transport cache is purged, the specified percentage (20 by default) of the total number of connections cached will be closed.
> `-ORBConnectionCacheLock` locktype | Specify the type of lock to be used by the Connection Cache. Possible values for lock type are `thread`, which specifies that an inter-thread mutex is used to guarantee exclusive access, and `null`, which specifies that no locking be performed. The default is thread.
> `-ORBCorbaObjectLock` locktype | Specify the type of lock to be used by CORBA::Object. The lock is needed within the CORBA object to synchronize the state when the same object is shared by multiple threads. Possible values for lock type are `thread`, which specifies that an inter-thread mutex is used to guarantee exclusive access, and `null`, which specifies that no locking be performed. The default is thread. The `null` lock option is useful when there is only one thread in the system. This option can be used to minimize the amount of memory consumed by the locks in applications where locks are not needed. The memory growth problem gets particularly exacerbated for applications dealing with hundreds and thousands of objects.
> `-ORBObjectKeyTableLock` locktype | Specify the type of lock to be used by the ObjectKey table. ObjectKey table keeps track of the ObjectKeys that are generated and made available through IORs. The table manages the life time of the object keys within the ORB through a reference counting mechanism. Possible values for lock type are `thread`, which specifies that an inter-thread mutex is used to guarantee exclusive access, and `null`, which specifies that no locking be performed. The default is thread.
> `-ORBFlushingStrategy` type | By default TAO provides three strategies to flush queued messages. The `leader_follower` strategy uses the Reactor and non-blocking I/O to send the outgoing messages, this strategy participates in the Leader/Followers protocol to synchronize access to the Reactor. The `reactive` strategy uses the Reactor but does not take part in the Leader/Followers protocol, thus it is better used only in single threaded applications. Finally, the `blocking` strategy flushes the queue as soon as it becomes "full", and blocks the thread until all the data is sent.
> `-ORBDropRepliesDuringShutdown` boolean (0|1) | Strategy to make the ORB wait for replies to show up even if the ORB is shutdown. The default is to drop replies. For example, clients comunicating with misbehaved servers will continue to hang if replies don't show up and even if the client ORB is shutdown from another thread. This strategy helps the ORB decide to wait for the replies or drop replies. Some clients may not want to drop replies, and may want all their requests to be processed until ORB::destroy () is called. Setting the value of this option to 0 would help with that.
> `-ORBOutputCDRAllocator` mmap|local_memory_pool | When the define `TAO_USE_OUTPUT_CDR_MMAP_MEMORY_POOL` is set to 1 then always the mmap pool will be used.
> `-ORBZeroCopyWrite` | Use a zero copy write protocol, which at this moment the only option is sendfile. If your platform does support sendfile but you don't want that TAO uses it you can disable sendfile in TAO by add the define `TAO_HAS_SENDFILE 0` to your config.h file.

#### 1.2. Advanced_Resource_Factory

This factory is located in the `TAO_Strategies` library. It accepts the options below as well as those described above in the `Resource_Factory`. This factory can be loaded dynamically using a service configurator directive of the form (all on one line):

`dynamic Advanced_Resource_Factory Service_Object *`
`TAO_Strategies:_make_TAO_Advanced_Resource_Factory () "-ORBReactorType select_st"`

It can also be loaded statically by doing the following:

- Add `#include "tao/Strategies/advanced_resource.h"` to the file containing `main()`.
- Link the TAO_Strategies library into the executable.
- Specify a service configurator directive of the form: `static Advanced_Resource_Factory "-ORBReactorType select_st"`

You can omit the `#include` if you always use dynamic libraries.

Loading the `Advanced_Resource_Factory` disables the `Resource_Factory`. Any directives for the `Resource_Factory` will have no effect (and generate warnings telling you so). The following table lists the options that can be provided in double quotes. An example is available that shows how to specify this option in the svc.conf file.

> Option | Description
> --- | ---
> `-ORBReactorType` which | Specify what kind of reactor the ORB uses. The default reactor is the ACE_TP_Reactor.
> which | Reactor
> --- | ---
> `select_mt` | Use the multi-thread select-based reactor.
> `select_st` | Use the single-thread select-based reactor.
> `wfmo` | Use the WFMO reactor (Win32 only).
> `msg_wfmo` | Use the MsgWFMO reactor (Win32 only).
> `tp` | Use the `ACE_TP_Reactor`, a select based thread-pool reactor which is the default.
> `dev_poll` | Use the `ACE_Dev_Poll_Reactor`, a `/dev/poll` or Linux `sys_epoll()` based thread-pool reactor. It is intended to be a highly scalable replacement for the `select()` based reactors. The ACE_Dev_Poll_Reactor is currently only supported on HP-UX, Solaris and Linux. Be aware that dev_poll support is experimental!
> `-ORBReactorThreadQueue` which | Applies only to the `ACE_TP_Reactor`, i.e., when `-ORBReactorType` = `tp`, and specifies the order, last-in-first-out (which = `LIFO`), the default, or first-in-first-out (which = `FIFO`), in which waiting threads are selected to run by the `ACE_Select_Reactor_Token`.
> `-ORBInputCDRAllocator` which | Specify whether the ORB uses locked (which = `thread`) or lock-free (which = `null`) allocators for the incoming CDR buffers. Though `null` should give the optimal performance; we made the default `thread`. TAO optimizations for octet sequences will not work in all cases when the allocator does not have locks (for example if the octet sequences are part of a return value). Using locked allocators also allows the users to take advantage of the TAO octet sequence extensions to preserve the buffer after the upcall.
> `-ORBAMHResponseHandlerAllocator` which | Specify whether the ORB uses locked (which = `thread`) or lock-free (which = `null`) allocators for the AMH response handlers.
> `-ORBAMIResponseHandlerAllocator` which | Specify whether the ORB uses locked (which = `thread`) or lock-free (which = `null`) allocators for the AMI response handlers.
> `-ORBReactorRegistry` registry_type | This option is no longer supported. The Advanced Resource Factory will emit an error if you attempt its use.

#### 2. Server_Strategy_Factory

Certain elements of the ORB relate only to a TAO server. In this context, the server is any application that passively accepts connection from other processes and receives requests from those other connections. The server strategy factory is responsible for supporting features of TAO that are specific to servers. In particular, these include the following strategies:

- The concurrency strategies control the thread creation flags and other concurrency related behaviors.

- The demuliplexing strategies are used to locate servants inside the POA that are responsible for handling requests.

TAO provides a default server strategy factory called `Server_Strategy_Factory`

Typically, the following options are set via the service configurator (svc.conf) file. The following line in the svc.conf file (all in one line)

`static Server_Strategy_Factory "[list of options]"`

would load all the options listed within "". An example is available that shows how to specify this option in the `svc.conf` file.

> Option | Description
> --- | ---
> `-ORBConcurrency` which | Specify which concurrency strategy to use. Range of values is `reactive` for a purely Reactor-driven concurrency strategy or `thread-per-connection` for creating a new thread to service each connection. The default is reactive.
> `-ORBThreadPerConnectionTimeout` milliseconds | In many platforms it is impossible to interrupt the server threads created by the `thread-per-connection` model. This is because these threads are blocked in `read()` operations (and not in `select()`). As a workaround, the server threads periodically poll the ORB to find out if they should shutdown. This option controls the period of the polling, expressed in milliseconds. Applications that do not shutdown, or that can otherwise ensure that no server threads will be running at shutdown (for example if all the clients terminate before the server) can disable the polling using the magic value `INFINITE`. If the option is not provided then the ORB uses the compile-time flag `TAO_DEFAULT_THREAD_PER_CONNECTION_TIMEOUT`, this flag also expresses the time in milliseconds (as a string constant) and the magic value `"INFINITE"` can be used to disable polling entirely. This yields a slight performance improvement (around 1%).
> `-ORBActiveObjectMapSize` active object map size | Specify the size of the active object map. If not specified, the default value is 64.
> `-ORBUseridPolicyDemuxStrategy` user id policy based demultiplexing strategy | Specify the demultiplexing lookup strategy to be used with the user id policy. The demultiplexing strategy can be one of `dynamic` or `linear`. This option defaults to using the `dynamic` strategy.
> `-ORBSystemidPolicyDemuxStrategy` system id policy based demultiplexing strategy | Specify the demultiplexing lookup strategy to be used with the system id policy. The demultiplexing strategy can be one of `dynamic`, `linear`, or `active`. This option defaults to use the `dynamic` strategy when `-ORBAllowReactivationOfSystemids` is true, and to `active` strategy when `-ORBAllowReactivationOfSystemids` is false.
> `-ORBUniqueidPolicyReverseDemuxStrategy` unique id policy based reverse demultiplexing strategy | Specify the reverse demultiplexing lookup strategy to be used with the unique id policy. The reverse demultiplexing strategy can be one of `dynamic` or `linear`. This option defaults to using the `dynamic` strategy.
> `-ORBAllowReactivationOfSystemids` allows reactivation of system ids | Specify whether system ids can be reactivated, i.e., once an id that was generated by the system has been deactivated, will the user reactivate a new servant using the old id. If the user is not going to use this feature, the IORs can be shortened, an extra comparison in the critical upcall path removed, and some memory on the server side can be saved. The `ORBAllowReactivationOfSystemids` can be `0` or `1`. This option defaults to `1`.
> `-ORBActiveHintInIds` adds an active hint in ids | Specify whether an active hint should be added to ids. With active hints, ids can be found quickly. However, they lead to larger IORs. Note that this option is disregarded `if -ORBAllowReactivationOfSystemids` is set to `0`. The -ORBActiveHintInIds can be `0` or `1`. This option defaults to `1`.
> `-ORBPoaMapSize` poa map size | Specify the size of the POA map. If not specified, the default value is 24.
> `-ORBPersistentidPolicyDemuxStrategy` persistent id policy based demultiplexing strategy | Specify the demultiplexing lookup strategy to be used with the persistent id policy. The demultiplexing strategy can be one of `dynamic` or `linear`. This option defaults to using the `dynamic` strategy.
> `-ORBTransientidPolicyDemuxStrategy` transient id policy based demultiplexing strategy | Specify the demultiplexing lookup strategy to be used with the transient id policy. The demultiplexing strategy can be one of `dynamic`, `linear`, or `active`. This option defaults to using the `active` strategy.
> `-ORBActiveHintInPOANames` adds an active hint in poa names | Specify whether an active hint should be added to POA names. With active hints, POA names can be found quickly. However, they lead to larger IORs. The `-ORBActiveHintInPOANames` can be `0` or `1`. This option defaults to `1`.
> `-ORBThreadFlags` thread flags | Specify the flags used for thread creation. Flags can be any logical-OR combination of `THR_DETACHED`, `THR_BOUND`, `THR_NEW_LWP`, `THE_SUSPENDED`. The default is `THR_BOUND | THR_DETACHED` .
> `-ORBPOALock` lock type | Specify the type of lock to be used for POA accesses. Possible values for lock type are `thread`, which specifies that an inter-thread mutex is used to guarantee exclusive access, and `null`, which specifies that no locking be performed. The default is `thread`.

#### 3. Client_Strategy_Factory

Similar to the server strategy factory, the client strategy factory supports those elements of TAO that are specific to the behavior of clients, which are any CORBA applications that actively establish connections, submit requests, and perhap receive responses. The client strategy factory provides control over several resources used by clients. TAO provides a default client strategy factory called `Client_Strategy_Factory`.

Typically, the following options are set via the service configurator (`svc.conf`) file. The following line in the `svc.conf` file (all in one line)

`static Client_Strategy_Factory "[list of options]"`

would load all the options listed within "". An example is available that shows how to specify this option in the `svc.conf` file.

> Option | Description
> --- | ---
> `-ORBProfileLock` which | Specify the kind of synchronization primitive for the Profiles. Default is thread, which means that a regular thread mutex is used. The second option is null, which means a null lock is used. This makes sense in case of optimizations and is allowed when no forwarding is used or only a single threaded client.
> `-ORBClientConnectionHandler` MT | ST | RW / MT_NOUPCALL `-ORBWaitStrategy` MT / ST / RW / MT_NOUPCALL | Please note that these two options are synonymous and can be used interchangeably. ST means use the single-threaded client connection handler, i.e., the leader follower model will not be used. However, ST does support nested upcalls and handling of new requests while waiting for the reply from a server. MT means use the multi-threaded client connection handler which uses the leader follower model. This model allows the use of multiple threads with a single Reactor. RW selects a strategy that simply blocks in `recv()` when waiting for a response from the server instead of waiting in the Reactor using the Leader/Followers pattern. The RW strategy only works when the application does not have to worry about new request showing up when waiting for a response. Further, this strategy cannot be used with Asynchronous Method Invocation (AMI) calls and when using BiDIR GIOP. Therefore, this strategy is appropriate only for "pure" synchronous clients. Note that applications that require nested upcalls are not "pure" synchronous clients. Also note that this strategy will only affect two way calls, since there is no waiting for one way calls. This strategy can also be used in an application that is both a client and a server if the server side is handled by a separate thread and the client threads are "pure" clients. When this strategy is set to RW, then also the -ORBFlushingStrategy (which is part of the Resource_Factory) has to be set to `blocking`. `MT_NOUPCALL` (EXPERIMENTAL!) means use a client connection handler that participates in the leader-follower model like MT, but, like RW, does not allow handling of nested upcalls within the waiting thread. Note that with this strategy it is possible to "run out of threads" in a thread pool, and that TAO doesn't grow thread pools. Unlike RW, this does not require -ORBTransportMuxStrategy EXCLUSIVE. Default for this option is MT.
> `-ORBConnectionHandlerCleanup` 0 | 1 | Setting this option to 1 lets the ORB know that connection handlers setup for sending messages need to be cleaned up when errors occur. This option has an effect only for -ORBClientConnectionHandler RW . Rest of the options for -ORBCleintConnectionHandler have been automatically set up for cleaning the connection handlers. Setting the option to 1 has a side effect of registering and unregistering the connection handlers with the Reactor for every invocation, which has a negative impact on performance. Setting the option to 0 prevents this performance impact but leads to problems outlined here and here Default for this option is 0.
> `-ORBTransportMuxStrategy` EXCLUSIVE | MUXED | EXCLUSIVE means that the Transport does not multiplex requests on a connection. At a time, there can be only one request pending on a connection. MUXED means that Transport multiplexes more than one request at the same time on a connection. This option is often used in conjunction with AMI, because multiple requests can be sent "in bulk." Default for this option is MUXED.
> `-ORBConnectStrategy` type | TAO provides three strategies to connect to remote servers. The default leader_follower strategy uses the Reactor and non-blocking connects to connect and this strategy participates in the Leader/Followers protocol to synchronize access to the Reactor. The reactive strategy uses the Reactor for non-blocking connects but does not take part in the Leader/Followers protocol, thus it is better used only in single threaded applications. Finally, the blocked strategy as the name implies, blocks the thread until connection is complete. Some of the protocols in TAO (such as SHMIOP and SSLIOP) can only use the blocked strategy.

Back to the TAO component options and tuning documentation.