diff options
author | bala <bala@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2003-05-17 14:49:24 +0000 |
---|---|---|
committer | bala <bala@ae88bc3d-4319-0410-8dbf-d08b4c9d3795> | 2003-05-17 14:49:24 +0000 |
commit | 8e60d73dbc87fa761a2206cc891a6712cf0d4423 (patch) | |
tree | 41d75e12f499b7d6fecd5767270d38d69df18531 /TAO/docs/Options.html | |
parent | cca3a82b11577a298032232d1a719a7eb8da73f8 (diff) | |
download | ATCD-8e60d73dbc87fa761a2206cc891a6712cf0d4423.tar.gz |
ChangeLogTag:Sat May 17 09:44:42 2003 Balachandran Natarajan <bala@dre.vanderbilt.edu>
Diffstat (limited to 'TAO/docs/Options.html')
-rw-r--r-- | TAO/docs/Options.html | 2058 |
1 files changed, 1015 insertions, 1043 deletions
diff --git a/TAO/docs/Options.html b/TAO/docs/Options.html index 3b73cd0eab0..3e4c50de091 100644 --- a/TAO/docs/Options.html +++ b/TAO/docs/Options.html @@ -1,581 +1,760 @@ -<HTML> -<HEAD> - <!-- $Id$ --> - -<META NAME="GENERATOR" CONTENT="Adobe PageMill 2.0 Mac"> -<TITLE>Options for TAO Components</TITLE> +<HTML><HEAD><TITLE>Options for TAO Components</TITLE> </HEAD> +<BODY text=#000000 vLink=#ff0f0f link=#000fff bgColor=#ffffff> +<HR> -<BODY text = "#000000" -link="#000fff" -vlink="#ff0f0f" -bgcolor="#ffffff"> - -<HR><P> -<H3 ALIGN=CENTER>Options for TAO Components</H3> - -<H3>Overview</H3> - -TAO is an extremely flexible ORB that can be configured to meet a wide -range of application requirements. There are two primary mechanisms -for configuring TAO's behaviors: +<P> +<H2 align=center>Options for TAO Components</H2> +<H3>Table of Contents</H3> <UL> + <LI><A + href="#MOT">Introduction </A> + <LI><A href="#EXP">TAO's ORB Configuration Options</A> + <UL> + <LI><A href="#EV">Environment Variables</A> + <LI><A href="#CLO">Command-line Options</A> + <UL> + <LI><A + href="#CSCB">Controling Service Configurator Behavior </A> + <LI><A + href="#CDI">Controlling Debugging Information </A> + <LI><A + href="#ORP">Optimizing Request Processing </A> + <LI><A + href="#CMPS">Connection Management and Protocol Selection </A> + <LI><A + href="#MO">Miscellaneous Options </A></LI></UL> + <LI><A href="#SVC">Service Configuration File </A> + <UL> +<!-- Bala2, Doug - I had to modify here too - Andy --> + <LI><A href="#TRF">Simple and Advanced Resource Factories </A> + <UL> + <LI><A + href="#TDRF">TAO_Default_Resource_Factory + </A> + <LI><A + href="#TARF">TAO_Advanced_Resource_Factory + </A></LI></UL> + <LI><A + href="#TSSF">Server_Strategy_Factory + </A> + <LI><A + href="#TCSF">Client_Strategy_Factory + </A></LI></UL></LI></UL></LI></UL> +<HR> -<LI> Configurations that are global to an ORB, such as - a Name Service IOR or the default stringified IOR - format an ORB generates, are configured via environment - variables or command-line option flags passed to the - <code>ORB_init()</code> call. The internal structure for - command-line options is the traditional - <CODE>argc</CODE>/<CODE>argv</CODE> vector of strings style - popularized by C/C++ and Unix. By convention, - <code>ORB_init()</code> will consume any options that it recognizes, - removing them from <CODE>argv</CODE>, whereas unrecognized options - will not be removed. <P> - -<LI>Users can also modify the internal behaviors of an ORB by - dynamically linking <EM>ORB plug-ins</EM>, such as client/server connection - strategies, via a <code>svc.conf</code> file. These ORB plug-ins - can be fine-tuned by specifying their options in the - <code>svc.conf</code> file. - TAO provides several default plug-ins to deploy resource management - strategies, client/server strategies, and communication protocols - that can be further customized via the - <code>svc.conf</code> file options described in this page. Advanced - users can also develop their own plug-ins to customize TAO. - A <code>svc.conf</code> file, however, is not required to run TAO - programs since TAO provides a set of built-in strategies configured for - use with common use cases. Many of the default configuratiions for - these built-in strategies can also be customized when TAO is - compiled.<p> -</UL> - -<HR><P> -<H3><A NAME="ev">Environment Variables</A></H3> +<H3><B><A name=MOT>Introduction</A></B></H3> -The following environment variables are supported by TAO: +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: -<BLOCKQUOTE> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR> - <TH>Environment Variable</TH> - <TH>Description</TH> - </TR> - <TR> - <TD><CODE>NameServiceIOR</CODE> <EM>which</EM></TD> - <TD> - Specifies which IOR the Naming Service is listening on. - </TD> - </TR> - <TR> - <TD><CODE>NameServicePort</CODE> <EM>which</EM></TD> - <TD> - Specifies which port the Naming Service is listening on for multicast - requests. - </TD> - </TR> - <TR> - <TD><CODE>TradingServiceIOR</CODE> <EM>which</EM></TD> - <TD> - Specifies which IOR the Trading Service is listening on. - </TD> - </TR> - <TR> - <TD><CODE>TradingServicePort</CODE> <EM>which</EM></TD> - <TD> - Specifies which port the Trading Service is listening on for multicast - requests. - </TD> - </TR> - <TR> - <TD><CODE>ImplRepoServiceIOR</CODE> <EM>which</EM></TD> - <TD> - Specifies the IOR of an Implementation Repository. - </TD> - </TR> - <TR> - <TD><CODE>ImplRepoServicePort</CODE> <EM>which</EM></TD> - <TD> - Specifies which port the Implementation Repository is listening on for - multicast requests. - </TD> - </TR> -</TABLE> -</P> -</BLOCKQUOTE> - -<HR><P> - -<H3>Types of Options</H3> - -<blockquote> -<P>The following components can be tuned via the different options -mentioned above:</P> -<!-- We should try to split these across files. Looks cumbersome to --> -<!-- manage. --> <UL> - <LI><A HREF="#ORB"><CODE>CORBA::ORB</CODE></A> - <LI><A HREF="#DefaultResourceFactory"><CODE>TAO_Default_Resource_Factory</CODE></A> - <LI><A HREF="#AdvancedResourceFactory"><CODE>TAO_Advanced_Resource_Factory</CODE></A> - <LI><A HREF="#DefaultServer"><CODE>TAO_Default_Server_Strategy_Factory</CODE></A> - <LI><A HREF="#DefaultClient" TARGET="_top"><CODE>TAO_Default_Client_Strategy_Factory</CODE></A> - <LI><A HREF="#RT_ORB_Loader"><CODE>RT_ORB_Loader</CODE></A> -</UL> - -The details of the options are mentioned below. -</blockquote> - - -<HR><H3><A NAME="ORB"></A><CODE>CORBA::ORB</CODE></H3> - -<blockquote> -<P>Typically, the following options are set via command line -parameters that are eventually passed to CORBA::ORB_init (). </P> - -<p><em>Note:</em> <code>-ORBGlobalCollocation</code> flag has been -merged with <a href="#-ORBCollocation"><code>-ORBCollocation</code></a>. - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING= "0"> - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <!-- <TR NAME="ORBsvcconf"> --> - <tr> - <TD><CODE><A NAME="-ORBSvcConf">-ORBSvcConf</A></CODE> <EM>config filename</EM></TD> - <TD>Specifies the name of the file from which it will read dynamic service configuration - directives <EM>ala</EM> ACE's Service Configurator. By - default, a service configurator-based application will look - for a file named "svc.conf" in the current directory.</TD> - </TR> - <!-- <TR NAME="ORBsvcconf"> --> - <tr> - <TD><CODE>-ORBSvcConfDirective</CODE> <EM>directivestring</EM></TD> - <TD>Specifies a service configuration directive, which is passed to ACE's Service Configurator. - You can pass multiple of these options on the same command-line. </TD> - </TR> - <tr> - <TD><CODE><A - NAME="-ORBServiceConfigLoggerKey">-ORBServiceConfigLoggerKey</A></CODE> - <EM>logger key</EM></TD> - <TD>Set the logger key in the <CODE>ACE_Service_Config</CODE> - framework. Equivalent to the <CODE>-k</CODE> option on the ACE - service configurator class. - </TD> - </TR> - <TR> - <TD><CODE>-ORBDaemon</CODE></TD> - <TD>Specifies that the ORB should <I>daemonize</I> itself.</TD> - </TR> - <TR> - <TD><CODE>-ORBDebug</CODE></TD> - <TD>Turns on the output of debugging messages within ACE's Service Configurator - componentry.</TD> - </TR> - <TR> - <TD><CODE>-ORBDebugLevel</CODE> <EM>level</EM></TD> - <TD>Control the level of debugging in the ORB. Higher number produce - more output (try 10). - </TD> - </TR> - <TR> - <TD><CODE><A HREF="ORBEndpoint.html">-ORBEndpoint</A></CODE> - <EM>endpoint</EM></TD> - <TD><a name="-ORBEndpoint"></a>Tells the ORB to listen for requests on the - interface specified by <I><EM>endpoint</EM></I>. Endpoints are - specified using a URL style format. An endpoint has the form: - <blockquote><CODE> - protocol://V.v@addr1,...,W.w@addrN - </CODE></blockquote> - where <CODE>V.v</CODE> and <CODE>W.w</CODE> are optional protcol versions for - each address. An example of an IIOP endpoint is: - <blockquote><CODE> - iiop://<I><EM>hostname</EM></I>:<I><EM>port</EM></I> - </CODE></blockquote> - Sets of endpoints may be specified using multiple <CODE>-ORBEndpoint</CODE> - options or by delimiting endpoints with a semi-colon (;). For example, - <blockquote><CODE> - -ORBEndpoint iiop://localhost:9999 -ORBEndpoint uiop:///tmp/mylocalsock -ORBEndpoint shmiop://10002 - </CODE></blockquote> - is equivalent to: - <blockquote><CODE> - -ORBEndpoint 'iiop://localhost:9999;uiop:///tmp/mylocalsock;shmiop://10002' - </CODE></blockquote> - 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.<P> - If an endpoint is specified without an <CODE>addr</CODE> such as the following: - <blockquote><CODE> - -ORBEndpoint uiop:// -ORBEndpoint shmiop:// - </CODE></blockquote> - then a default endpoint will be created for the specified protocol. - <P> - This is a server side option. - </TD> - </TR> - - <TR> - <TD><CODE>-ORBObjRefStyle</CODE> <EM>which</EM></TD> - <TD>Specifies the user-visible style of object references. The range of values - is <CODE>IOR</CODE> (default), which is the traditional nonsensical object reference, - or <CODE>URL</CODE>, which looks more like a URL.</TD> - </TR> - <TR> - <TD><CODE>-ORBRcvSock</CODE> <EM>receive buffer size</EM></TD> - <TD><A NAME="-ORBRcvSock"></a>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.</TD> - </TR> - <TR> - <TD><CODE>-ORBSndSock</CODE> <EM>send buffer size</EM></TD> - <TD><A NAME="-ORBSndSock"></a>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.</TD> - </TR> - <TR> - <TD><CODE>-ORBNodelay</CODE> <EM>boolean (0|1)</EM></TD> - <TD><A NAME="-ORBNodelay"></a>Enable or disable the TCP_NODELAY - option. By default, TCP_NODELAY is enabled.</TD> - </TR> - <TR> - <TD><CODE>-ORBNameServicePort</CODE> <EM>portspec</EM></TD> - <TD>Specifies which port the Naming Service is listening on for - multicast requests. By default, - TAO_DEFAULT_NAME_SERVICE_REQUEST_PORT, which is 10013 is used.</TD> - </TR> - <TR> - <TD><CODE>-ORBTradingServicePort</CODE> <EM>portspec</EM></TD> - <TD>Specifies to which port the Trading Service is listening on for - multicast requests. By default, - TAO_DEFAULT_TRADING_SERVICE_REQUEST_PORT which is 10016 is used.</TD> - </TR> - <TR> - <TD><CODE>-ORBImplRepoServicePort</CODE> <EM>portspec</EM></TD> - <TD>Specifies to which port the Implementation Repository is listening on for - multicast requests. By default, - TAO_DEFAULT_IMPLREPO_SERVER_REQUEST_PORT which is 10018 is to - be used.</TD> - </TR> - <TR> - <TD><CODE>-ORBMulticastDiscoveryEndpoint</CODE> <EM>end_point</EM></TD> - <TD>Specifies the endpoint that should be used for locating the - Naming Service through multicast. <EM>end_point</EM> 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. - </TR> - <TR> - <TD><CODE>-ORBCollocation</CODE> <EM>global/per-orb/no</EM></TD> - <TD><a name="-ORBCollocation"></a>Specifies the use of collocation - object optimization. If <em>global</em> is - specified, objects in the same process will be treated as collocated. - If <em>per-orb</em> is specified, only objects in the same ORB are - treated as collocated. When <em>no</em> is specified, no objects are - treated as collocated. Default is global.</TD> - </TR> - <TR> - <TD> - <CODE>-ORBCollocationStrategy</CODE> <EM>thru_poa/direct</EM> - </TD> - <TD> - Specifies what kind of collocated object to use. If the - <em>thru_poa</em> strategy is used, TAO uses the collocation - object implementation that respects POA's current state and - policies. When using the <em>direct</em> strategy, method - invocations on collocated objects become direct calls to servant - without checking POA's status (which translates to better - performance.) Notice that the interfaces that you wish to use - direct collocation with must be compiled with <code> - <a href="compiler.html#collocation-stubs">-Gd</a> - </code>. Default is thru_poa. - </TD> - </TR> - <TR> - <TD><CODE>-ORBCDRTradeoff</CODE> <EM>maxsize</EM></TD> - <TD><A name="-ORBCDRTradeoff"></a>Control the strategy to tradeoff - between copy vs. no copy marshalling of octet sequences. - If an octet sequence is smaller than <EM>maxsize</EM> and the current - message block contains enough space for it the octet sequence is - copied instead of appended to the CDR stream. By default, - ACE_DEFAULT_CDR_MEMORY_TRADEOFF is used. - </TD> - </TR> - <TR> - <TD><CODE>-ORBSkipServiceConfigOpen</CODE></TD> - <TD><A name="-ORBSkipServiceConfigOpen"></a>Do not call the -<code>ACE_Service_Config::open</code> method when initializing the -ORB. This option is generally only useful when dynamically loading -the ORB. - <P> - <FONT COLOR=RED>This option is <STRONG>deprecated</STRONG>. It - is no longer needed since the Service Configurator is now - reentrant and thread-safe.</FONT> - - </TD> - </TR> - <TR> - <TD><CODE>-ORBDottedDecimalAddresses</CODE> <EM>boolean (0|1)</EM></TD> - <TD><A name="-ORBDottedDecimalAddresses"></a> Use the dotted decimal - notation for addresses. This option helps to work around - broken DNS implementations and may also reduce the time spent - resolving IP addresses. By default domain names are used in IORs.</TD> - </TR> - <TR> - <TD><CODE>-ORBInitRef</CODE> <EM>ObjectId=IOR</EM></TD> - <TD><A name="-ORBInitRef"></a> 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 - the string_to_object () method and used as a boot-strapping - mechanism by the resolve_initial_references () method. The mappings - specified through this argument override the orb-install-time - defaults. The file://<I>pathname</I> interprets the contents of the - <I>pathname</I> file as an object reference in any of the above - formats. - </TD> - </TR> - <TR> - <TD><CODE>-ORBDefaultInitRef</CODE> <EM>IOR prefix</EM></TD> - <TD><A name="-ORBDefaultInitRef"></a> This argument allows - resolution of initial references not explicitly specified with - -ORBInitRef. It requires a URL prefix that, after appending a - slash '/' ('|' for 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 - corbaloc. - </TD> - </TR> +<LI><B>Settings</B>, 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. <P> - <TR> - <TD><CODE>-ORBStdProfileComponents</CODE> <EM>boolean (0|1)</EM></TD> - <TD><A name="-ORBStdProfileComponents"></a> If <EM>0</EM> 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 - (check orbconf.h).</TD> - </TR> +<LI><B>Resources</B>, which are objects used internally by TAO, such +as a <EM>reactor</EM> framework that demultiplexes new connection and +data requests from a client or <EM>synchronization mechanisms</EM> +used to regulate access to certain parts of the ORB.<P> - <TR> - <TD><CODE>-ORBResources</CODE> <EM>which</EM></TD> - <TD><A name=-ORBResources> <FONT COLOR=RED>This option is - <STRONG>deprecated</STRONG>, since this option has almost - negligible effect on the ORB</FONT>. The right type of resources - are selected by the ORB during runtime. For example the memory for - the output datapath always defaults to TSS. The inour data path - always defaults to stack for small messages and global pool for - larger messages. There was no effect with the use of this option. - </TD> - </TR> +<LI><B>Strategies</B>, which are objects that use the <B>Resource</B> +entities to perform various ORB tasks, such as connection management, +concurrency, and demultiplexing. <P> +<LI><B>Factories</B>, 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. <P> - <TR> - <TD><CODE>-ORBUseIMR</CODE> <EM>boolean (0|1)</EM></TD> - <TD><A name=-ORBUseIMR></A>This argument specifies that for POAs with the - PERSISTENT policy, that the Implementation Repository should be used for - notification of startup and shutdown and Object References should be changed - to use the Implementation Repository also. - </TD> - </TR> +</UL> - <TR> - <TD><CODE>-ORBLogFile</CODE> <EM>log file name</EM></TD> - <TD><A name=-ORBLogFile></A>Causes all ACE_DEBUG and ACE_ERROR - output to be redirected to the specified file. - </TD> - </TR> +The set of TAO ORB configuration options that are represented by the +settings, resources, strategies, and factories can be specified via +<B>environment variables</B>, <B>service configuration files</B>, and +<B>command-line arguments</B>, as outlined below: - <TR> - <TD><CODE>-ORBSingleReadOptimization</CODE> <EM>boolean (0|1)</EM></TD> - - <TD><A name=-ORBSingleReadOptimization></A>This option controls - single read optimzations when reading requests. If this option is - off, the ORB will do two reads to read a request. One to read the - request header and the other to read the request payload. If this - option is on, the ORB will do a read of size - <EM>TAO_MAXBUFSIZE</EM>, hoping to read the entire request. - However, in this case, there is a chance of reading more than one - request. If any additional requests have been read, they are - queued up for processing later.<p> - - This option defaults to <EM>1</EM> because it can provide better - performance since one less read is performed. However, in the - case of RT-CORBA, this option should be set to <EM>0</EM>. - Consider the following scenario: two requests are read from one - socket; the additional request is queued; a Reactor notify is - dispatch to awake a follower threads; at this time, new requests - arrive on others sockets of higher priority; however, since - notifies are given preferences over normal I/O, the lower priority - queued message will be processed before the newly arrived higher - priority request. - - </TD> - </TR> - <TR> - <TD><CODE>-ORBListenEndpoints</CODE> <EM>endpoint</EM></TD> - <TD><A name=-ORBListenEndpoints></A>This Option is similar to - ORBEndPoint option described above. The ORBEndpoint option - would be deprecated in later versions on TAO. This option is - introduced with Object Reference Template Specification. - </TD> - </TR> +<UL> - <TR> - <TD><CODE>-ORBId</CODE> <EM>ORB_NAME</EM></TD> - <TD><A name=-ORBId></A>This option allows setting the name of an - ORB as the Option name suggests. - </TD> - </TR> +<LI> <B>Environment variables</B> are limited to specifying the +interoperable object reference (IOR) and port number of TAO's Naming +Service, Trading Service and Implementation Repository. Command-line +options and service configurator files are more powerful since they +can specify and modify the values of the various TAO resources, +strategies, and factories. <P> + +<LI> The <B>Service Configurator</B> 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 <font face="Courier +New">svc.conf</font>. <P> + +<LI> <B>Command-line options</B> are passed to the ORB initialization +factory method, <CODE>CORBA::ORB_init()</CODE>, by an application +using the standard <i>argc, argv</i> tuple passed to the application's +<CODE>main()</CODE>. In contrast, the service configuration file is +opened and its options parsed by TAO's ACE Service Configurator +framework during the execution of +<CODE>CORBA::ORB_init()</CODE>method.<P> - <TR> - <TD><CODE>-ORBServerId</CODE> <EM>server_id</EM></TD> - <TD><A name=-ORBId></A>This option allows setting a name/id to - a server to uniquely identify a server to the Implementation Repository. - </TD> - </TR> +</UL> +<P><HR align=left width=25%><P> +<h3>Choosing the Right Approach</h3> + +Command-line options are useful when there is a fixed set of +configuration options each of which has a predefined list of +alternative values. Conversely, the 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 <br> + +<Ul> + <li>configure the existing components (<EM>i.e.</EM>, resources, + strategies and factories) based on the predefined list of + alternatives that TAO provides or<P> + </li> + <li>extend the existing factories by providing user-defined + components and dynamically load them through the service + configurator mechanism. </li> +</Ul> +Additionally, the service configurator mechanism provides a way for +the application to control the behavior of the ORB using extensible +configuration information. + +Note that the command-line options and the service configurator +options cannot be used interchangeably. +<!-- Andy, Bala, can you please add a sentence or two explaining why --> +<!-- this is the case?! It's always been mysterious to me *why* this --> +<!-- is the case! --> +<!-- Doug - see below after these bunch of comments - Andy --> +<!-- Tao, Is this needed? --> +<!--Tao added, i think sentences below is a source of confusion--> +<!--webbot bot="PurpleText" PREVIEW="right. this line seems to be a + repition to me. Let us zap it - Andy" --> +<!-- Andy, Bala, I think we need something along these lines to --> +<!-- explain why it's the case we distinguish command-line options and --> +<!-- the svc.conf options! Perhaps we just need to reword this stuff --> +<!-- better? --> +<!-- Doug - here is the reworded senetence - Andy --> + +In summary, 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 <A HREF="#SVC">service configuration files</A>. <P> + +<HR> + +<H3><B><A name=EXP>TAO's ORB Configuration Options</A></B></H3> + +This section provides a detailed overview of how to configure TAO's +options using environment variables, command-line options, and service +configuration files.<P> + +<HR align=left width=25%> +<h3><A name=EV>Environment Variables</A></h3> + +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. -</TABLE> -</P> -</blockquote> -</blockquote> +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Environment Variable</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE>NameServiceIOR</CODE> <EM>which</EM></TD> + <TD>Specifies the IOR for the Naming Service that can be used to + bootstrap the Naming Service object reference within an + application. </TD></TR> + <TR> + <TD><CODE>NameServicePort</CODE> <EM>which</EM></TD> + <TD>Specifies which port the Naming Service is listening on for + multicast requests. </TD></TR> + <TR> + <TD><CODE>TradingServiceIOR</CODE> <EM>which</EM></TD> + <TD>Specifies the IOR for the Trading Service. </TD></TR> + <TR> + <TD><CODE>TradingServicePort</CODE> <EM>which</EM></TD> + <TD>Specifies which port the Trading Service is listening on for + multicast requests. </TD></TR> + <TR> + <TD><CODE>ImplRepoServiceIOR</CODE> <EM>which</EM></TD> + <TD>Specifies the IOR for the Implementation Repository. </TD></TR> + <TR> + <TD><CODE>ImplRepoServicePort</CODE> <EM>which</EM></TD> + <TD>Specifies which port the Implementation Repository is listening on + for multicast requests. </TD></TR></TBODY></TABLE></P></BLOCKQUOTE> + +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: <P> +<code> +% NameService.exe -ORBEndpoint iiop://localhost:12345 +</CODE><P> +<CODE> +% client.exe -ORBInitRef NameService=iiop://localhost:12345" +</code><P> + +An explanation of these command-line options appears below. <P> + +<HR align=left width=25%> +<H3><A name=CLO>Command-line Options</A></h3> + +TAO's run-time behavior can also be controlled by passing options via +the CORBA initialization method <CODE>CORBA::ORB_init()</CODE>. ORB +initialization options are commonly passed into the program from the +command-line, using the <CODE>argc</CODE> and <CODE>argv</CODE> +parameters available to the <CODE>main()</CODE> function. <P> + +Command-line options can be classified into the following groups +according to their purposes:</P> + +<OL> + <LI><A + href="#CSCB">Controlling + Service Configurator Behavior</A> + <LI><A href="#CDI">Controlling + Debugging Information</A> + <LI><A href="#ORP">Optimizing + Request Processing</A> + <LI><A href="#CMPS">Connection + Management and Protocol Selection</A> + <LI><A + href="#MO">Miscellaneous + Options</A> +</OL> + +We describe each of these five groups of options below. <P> + +<h4><A name=CSCB>1. Controlling Service Configurator Behavior</A></h4> + +The options described below influence the behavior of the ORB's <A +HREF="#SVC">service configurator</CODE>. <P> +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Option</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE>-ORBSvcConf</CODE> <EM>config filename</EM></TD> + <TD>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 <CODE>"svc.conf"</CODE> in the current directory. </TD></TR> + <TR> + <TD><CODE>-ORBSvcConfDirective</CODE> <EM>directivestring</EM></TD> + <TD>Specifies a service configuration directive, which is passed to + the Service Configurator. You can pass multiple of these options on + the same command-line. </TD></TR> +</TBODY></TABLE></P></BLOCKQUOTE> + +<h4><A name=CDI>2. Controlling Debugging Information</A></h4> + +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.<P> -<HR><H3><A NAME="DefaultResourceFactory"></A><CODE>TAO_Default_Resource_Factory</CODE></H3> +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Option</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE>-ORBDebug</CODE></TD> + <TD>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.</TD></TR> + <TR> + <TD><CODE>-ORBDebugLevel </CODE><EM>level</EM></TD> + <TD>Control the level of debugging in the ORB. + Higher numbers generate more output (try 10). The default value + of this option is 0.</TD></TR> + <TR> + <TD><CODE>-ORBLogFile</CODE> <EM>Logfilename</EM></TD> + <TD>Causes all <CODE>ACE_DEBUG</CODE> and <CODE>ACE_ERROR</CODE> + output to be redirected to the designated + <CODE>Logfilename</CODE>. </TD></TR> + <TR> + <TD><CODE>-ORBObjRefStyle</CODE> <EM>IOR/URL</EM></TD> + <TD>Specifies the user-visible style of object references. + The <CODE>IOR</CODE> style (default) is the conventional CORBA object + reference, whereas the <CODE>URL</CODE> style looks more like a URL. +</TD></TR></TBODY></TABLE></P></BLOCKQUOTE> + +<h4><A name=ORP>3. Optimizing Request Processing</A></h4> + +It is often possible to <A HREF="performance.html">increase throughput +and reduce latency</A> by optimizing certain stages of request +processing in the ORB. The following options control various +optimizations during request processing.<P> -<blockquote> -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) +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Option</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE>-ORBCDRTradeoff</CODE> <EM>maxsize</EM></TD> + <TD><A name=-ORBCDRTradeoff></A>Control the strategy to tradeoff between + copy vs. no copy marshaling of octet sequences. If an octet sequence is + smaller than <CODE>maxsize</CODE> (which defaults to + <CODE>ACE_DEFAULT_CDR_MEMORY_TRADEOFF</CODE>) -- and the + current message block contains + enough space for it -- the octet sequence is copied instead of + appended to the CDR stream. + </TD></TR> + <TR> + <TD><CODE>-ORBCollocation</CODE> <EM>global/per-orb/no</EM></TD> + <TD><A name=-ORBCollocation></A>Specifies the use of collocation object + optimization. If <CODE>global</CODE> is specified (default), + objects in the same process will be treated as + collocated. If <CODE>per-orb</CODE> is specified, + only objects in the same ORB are treated as collocated. When + <EM>no</EM> + is specified, no objects are treated as collocated. </TD></TR> + <TR> + <TD><CODE>-ORBCollocationStrategy</CODE> <EM>thru_poa/direct</EM> </TD> + <TD>Specifies what type of collocated object to use. If the + <CODE>thru_poa</CODE> (default) strategy is used, TAO uses the + collocation object implementation that respects POA's + current state and policies. When using the + <CODE>direct</CODE> strategy, method invocations on + collocated + objects become direct calls to servant without checking POA's status, + which can increase performance. If you use the + <CODE>direct</CODE> strategy, your interfaces must be + compiled with the + <CODE><A + href="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/docs/compiler.html#collocation-stubs">-Gd</A></CODE> IDL <A HREF="compiler.html">compiler option</a>. </TD></TR> + <TR> + <TD><CODE>-ORBNodelay</CODE> <EM>boolean (0|1)</EM></TD> + <TD><A name=-ORBNodelay></A>Enable or disable the <CODE>TCP_NODELAY</CODE> + option (Nagle's algorithm). By + default, <CODE>TCP_NODELAY</CODE> is enabled.</TD></TR> + <TR> + <TD><CODE>-ORBRcvSock</CODE> <EM>receive buffer size</EM></TD> + <TD><A name=-ORBRcvSock></A>Specify the size of the socket receive + buffer as a positive, non-zero integer. If not specified, the + <CODE>ACE_DEFAULT_MAX_SOCKET_BUFSIZ</CODE> default is used.</TD></TR> + <TR> + <TD><CODE>-ORBSndSock</CODE> <EM>send buffer size</EM></TD> + <TD><A name=-ORBSndSock></A>Specify the size of the socket send buffer + as a positive, non-zero integer. If not specified, the + <CODE>ACE_DEFAULT_MAX_SOCKET_BUFSIZ</CODE> default is used.</TD></TR> + <TR> + <TD><CODE>-ORBStdProfileComponents</CODE> <EM>boolean (0|1)</EM></TD> + <TD><A name=-ORBStdProfileComponents></A>If <EM>0</EM> 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 (check orbconf.h).</TD></TR> + <TR> + <TD><CODE>-ORBSingleReadOptimization</CODE> <EM>boolean (0|1)</EM></TD> + <TD><A name=-ORBSingleReadOptimization></A>This option controls + whether TAO's ``single read optimization'' is used when receiving + requests. If this option is disabled (<code>0</code>), 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 + (<CODE>1</CODE>), the ORB will do a read of size + <CODE>TAO_MAXBUFSIZE</CODE>, hoping to read the + entire request. If more than one request is read they will be + queued up for processing later. <P> + This option defaults to <CODE>1</CODE> because it can provide better + performance. However, in the case of RT-CORBA, this option should be set to <code>0</code>. 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.</P></TD></TR></TBODY></TABLE></P></BLOCKQUOTE> + +<h4><A name=CMPS>4. Connection Management and Protocol Selection</A></h4> + +ORBs send and receive requests and replies using various <A +pluggable_protocols">transport protocols</a>. Each protocol has +its own concept of an <A +http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/docs/ORBEndpoint.html">endpoint</CODE>. +The following options manage connections and control protocol +selection within a CORBA application.<P> + +<!--- TAO, please add the options in italics --> +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Option</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE>-ORBDefaultInitRef</CODE> <EM>IOR prefix</EM></TD> + <TD><A name=-ORBDefaultInitRef></A>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 <CODE>corbaloc</CODE> mechanism in + the CORBA <A HREF="INS.html">Interoperable Naming Service</CODE>. </TD></TR> + <TR> + <TD><CODE>-ORBDottedDecimalAddresses</CODE> <EM>boolean (0|1)</EM></TD> + <TD><A name=-ORBDottedDecimalAddresses></A>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. By default, this option is disabled + (<CODE>0</CODE>) since domain names are the standard address + notation for IORs.</TD></TR> + <TR> + <TD><CODE>-ORBEndpoint</CODE> + <EM>endpoint</EM></TD> + <TD><A name=-ORBEndpoint></A>This option is similar to the + <CODE>-ORBListenEndPoints</CODE> option described below. + <FONT color=red>This option will be deprecated in later + versions on TAO since the CORBA specification now defines the + <CODE>-ORBListenEndpoints</CODE> option instead. </FONT> + </TD></TR> + <TR> + <TD><CODE>-ORBListenEndpoints</CODE> <EM>endpoint</EM></TD> + <TD><A name=-ORBListenEndpoints></A> This option was introduced with + the CORBA <A href="http://cgi.omg.org/docs/orbos/01-01-04.pdf"> + ORT </a> (Object Reference Template) specification. It + instructs a server ORB to listen for requests on the + interface specified by <code>endpoint</code>. + TAO <A + href="http://cvs.doc.wustl.edu/viewcvs.cgi/TAO/docs/ORBEndpoint.html?rev=HEAD"> + endpoints</A> are specified using a URL style format. An + endpoint has the form: + <BLOCKQUOTE><CODE>protocol://V.v@addr1,...,W.w@addrN + </CODE></BLOCKQUOTE>where <CODE>V.v</CODE> and <CODE>W.w</CODE> are + optional protocol versions for each address. An example of an IIOP + endpoint is: + <BLOCKQUOTE><CODE>iiop://<I><EM>hostname</EM></I>:<I><EM>port</EM></I> + </CODE></BLOCKQUOTE>Sets of endpoints may be specified using multiple + <CODE>-ORBEndpoint</CODE> options or by delimiting endpoints with a + semi-colon (;). For example, + <BLOCKQUOTE><CODE>-ORBEndpoint iiop://localhost:9999 -ORBEndpoint + uiop:///tmp/mylocalsock -ORBEndpoint shmiop://10002 + </CODE></BLOCKQUOTE>is equivalent to: + <BLOCKQUOTE><CODE>-ORBEndpoint + 'iiop://localhost:9999;uiop:///tmp/mylocalsock;shmiop://10002' + </CODE></BLOCKQUOTE>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. + <P>If an endpoint is specified without an <CODE>addr</CODE> such as the + following: + <BLOCKQUOTE><CODE>-ORBEndpoint uiop:// -ORBEndpoint shmiop:// + </CODE></BLOCKQUOTE>then a default endpoint will be created for the + specified protocol. <P></TD></TR> + <TR> + <TD><CODE>-ORBImplRepoServicePort</CODE> <EM>portspec</EM></TD> + <TD>Specifies which port the Implementation Repository is listening + on for multicast requests. By default, the + <CODE>TAO_DEFAULT_IMPLREPO_SERVER_REQUEST_PORT</CODE> (10018) is used.</TD></TR> + <TR> + <TD><CODE>-ORBInitRef</CODE> <EM>ObjectId=IOR</EM></TD> + <TD><A name=-ORBInitRef></A>Allows specification of an arbitrary object + reference for an initial service. The IOR could be in any one of the + following formats: OMG <CODE>IOR</CODE>, <CODE>URL</CODE>, + <CODE>corbaloc</CODE> (including <CODE>uioploc</CODE>) or <CODE>file</CODE>. + <CODE>corbaloc</CODE> is a multiple end-point IOR understood + by <CODE>ORB::string_to_object()</CODE> and used as a + boot-strapping mechanism by the + <CODE>ORB::resolve_initial_references()</CODE>. The mappings specified through + this argument override the ORB install-time defaults. The + <CODE>file://pathname</CODE> interprets the contents of the <CODE>pathname</CODE> + file as an object reference in any of the above formats. </TD></TR> + <TR> + <TD><CODE>-ORBMulticastDiscoveryEndpoint</CODE> <EM>endpoint</EM></TD> + <TD>Specifies the <CODE>endpoint</CODE> that should be used for locating the Naming + Service through multicast. <EM>endpoint</EM> is of the form + <CODE>ip-number:port-number</CODE> (<EM>e.g.</EM>, + <CODE>"tango.cs.wustl.edu:1234"</CODE> or + <CODE>"128.252.166.57:1234"</CODE>). If there is no + <CODE>':'</CODE> in the end_point it is assumed to be a port + number, with the IP address being <CODE>INADDR_ANY</CODE>. </TD> + <TR> + <TD><CODE>-ORBNameServicePort</CODE> <EM>portspec</EM></TD> + <TD>Specifies which port the Naming Service is listening on for + multicast requests. By default, the <CODE>TAO_DEFAULT_NAME_SERVICE_REQUEST_PORT</CODE> + (10013) value is used.</TD></TR> + <TR> + <TD> <A +http://cvs.doc.wustl.edu/viewcvs.cgi/*checkout*/TAO/docs/ORBEndpoint.html?rev=HEAD"><CODE>-ORBTradingServicePort</CODE> <EM>portspec</EM></TD> + <TD> <A +http://cvs.doc.wustl.edu/viewcvs.cgi/TAO/docs/ORBEndpoint.html?rev=HEAD">Specifies to which port the Trading Service is listening on for + multicast requests. By default, the <CODE>TAO_DEFAULT_TRADING_SERVICE_REQUEST_PORT</CODE> + (10016) value is used.</TD></TR> + <TR> + <TD> <CODE>-ORBUseIMR</CODE> <EM>boolean (0|1)</EM></TD> + <TD>This argument specifies that for POAs with + the <CODE>PERSISTENT</CODE> policy, that the TAO <A + HREF="implrepo/">Implementation Repository</A> should be used + for notification of startup and shutdown and object references should be + changed to use the Implementation Repository also. + </TD></TR> + </TD></TR></TBODY></TABLE></P></BLOCKQUOTE> + +<h4><A name=MO>5. Miscellaneous Options</A></h4> + +Options in this category don't control the behavior of the ORB in +terms of resouces or strategies. They are helper options provided for +specific application requirements. -<p><code>static Resource_Factory "[list of options]"</code></p> -would load all the options listed within "". +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Option</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE>-ORBId</CODE> <EM>orb_name</EM></TD> + <TD><A name=-ORBId></A>This option allows the name of an ORB to + be set to <CODE>orb_name</CODE>. The ORBId will be passed to + the ORB_init() method to differentiate coexisting ORBs (when + there are more than one ORBs).</TD></TR> + <TR> + <TD><CODE>-ORBServerId</CODE> <EM>server_id</EM></TD> + <TD><A name=-ORBId></A>This option allows setting a name/id to a + server + <!-- Tao, could you please provide the actual link? --> + to uniquely identify a server to TAO's <A HREF="implrepo">Implementation Repository</A>. </TD></TR> + <TR> + <TD><CODE>-ORBDaemon</CODE></TD> + <TD>Specifies that the ORB should <EM>daemonize</EM> itself, + <em>i.e.</EM>, run as a background process. This option is only + meaningful on OS platforms that support daemonization.</TD></TR> +</TBODY></TABLE></P></BLOCKQUOTE> +<P></P> + +<HR align=left width=25%> + +<H3><A name=SVC>The Service Configurator File</A></H3> + +Internally, TAO uses the <A +href="http://www.cs.wustl.edu/~schmidt/PDF/Svc-Conf.pdf">ACE service +configurator framework</A> that allows applications to configure the +ORB at run-time. Applications provide a file by name +<CODE>svc.conf</CODE> 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: </p> + +<OL> + <LI><A href="#TRF">Default Resource and Advanced Resource Factories :</A> + 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. <P> + <LI> <A href="#TSSF">Server Strategy Factory:</A> 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.<P> + <LI> <A href="#TCSF">Client Strategy Factory:</A> 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.<P> +</OL> + +Options specified via a <CODE>svc.conf</CODE> file can represent +either the components provided by TAO (including the +<CODE>Resource_Factory</CODE>, and the +<CODE>Server_Strategy_Factory</CODE> and +<CODE>Client_Strategy_Factory</CODE>) or +customized components developed by the users. The service configurator file +(<CODE>svc.conf</CODE>) provided by the user identifies the components +to be loaded with the required strategies for each component. <p> + +A <CODE>svc.conf</CODE> file is <EM><B>not</B></EM> required to run +TAO applications since TAO provides a set of default values for +strategies useful for the most common use cases, <EM>i.e.</EM>, the +default values are set for all options. When a TAO application calls +<CODE>CORBA::ORB_init()</CODE> it will try to find the +<CODE>svc.conf</CODE> 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.</P> + +<hr align=left width=25%> +<!-- Bala, is there a specific name for this, i.e., can you use the --> +<!-- "real" name here rather than the "conceptual" name?! --> +<!-- The conceptual name is ok here. See the sub bullets below - Andy--> +<!-- I am using the name the Default here to be in sync with other things--> +<h4><A name=TRF>1. Default and Advanced Resource Factories</A></h4> + +Many resources required by TAO's ORB core are fixed, though there is +some flexibility 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 +comprise <CODE>Resource_Factory</CODE> and +<CODE>Advanced_Resource_Factory</CODE>. TAO provides defaults of these +factories as well as specialized resource factories described below: +<!-- Doug, Bala2 - I inserted the above sentence - Andy --> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Resource Factory</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE><A + href="#TDRF">Resource Factory</A></CODE></TD> + <TD>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. + </TD></TR> + <TR> + <TD><CODE><A + href="#TARF">Advanced Resource Factory</A></CODE></TD> + <TD>This factory provides more advanced configuration options in the + addition to all the features of the default resource factory.<BR><BR>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.<BR><BR>The advanced resource factory inherits from the + default resource factory and accepts all of its options in + addition to its own. </TD></TR> + + <TR> + <TD><CODE>Qt Resource Factory</CODE></TD> + <TD>This is a specialized resource factory providing the means for + integrating with the Qt GUI toolkit from Trolltech. </TD></TR> + <TR> + <TD><CODE>Xt Resource Factory</CODE></TD> + <TD>This is a specialized resource factory providing the means for + integrating with the X Window System's Xt Intrinsics toolkit. + </TD></TR></TBODY></TABLE></P></BLOCKQUOTE> +<P></P> + +<h5><A name=TDRF>(a). Resource_Factory</A></h5> + +Typically, the above option are exercised via the service configurator +(svc.conf) file. The following line in the <CODE>svc.conf</CODE> file +(all in one line) <P> +<CODE>static Resource_Factory "[list of options]"</CODE><P>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. <A href="http://cvs.doc.wustl.edu/viewcvs.cgi/TAO/tests/LongUpcalls/svc.conf?rev=HEAD"> +This</A> shows an example on how this is used.<P> + +<TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> <TR> <TH>Option</TH> - <TH>Description</TH> - </TR> - <TR> - <TD><CODE>-ORBResources</CODE> <EM>which</EM></TD> - <TD><A name=-ORBResources> <FONT COLOR=RED>This option is - <STRONG>deprecated</STRONG>, since this option has almost - negligible effect on the ORB</FONT>. The right type of resources - are selected by the ORB during runtime. For example the memory for - the output datapath always defaults to TSS. The inour data path - always defaults to stack for small messages and global pool for - larger messages. There was no effect with the use of this option. - </TR> + <TH>Description</TH></TR> <TR> <TD><CODE>-ORBReactorMaskSignals</CODE> <EM>0/1</EM></TD> - <TD>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 way. - Disabling the mask can improve performance by reducing the - number of kernel level locks. - </TD> - </TR> -<TR> - <TD><CODE>-ORBProtocolFactory</CODE> <EM>factory</EM></TD> - <TD><a name="-ORBProtocolFactory"></a> - Specify which pluggable protocol factory to load. By default, - only the factory for the IIOP protocol - (<code>IIOP_Factory</code> is loaded. - <p> - For example, if some protocol called <em><code>Foo</code></em> whose - factory was called <em><code>Foo_Factory</code></em> was available, - then it could be loaded into TAO by specifying - <code>-ORBProtocolFactory Foo_Factory</code> in the service - configurator file. The - <em><code>Foo</code></em> pluggable protocol would then be available - for use. - </TD> -</TR> -<TR> - <TD><CODE>-ORBIORParser</CODE> <EM>parser</EM></TD> - <TD><a name="-ORBIORParser"></a> - Name an IOR Parser to load. - IOR Parsers are used to interpret strings passed to - <CODE>ORB::string_to_object()</CODE>. - By default the ORB can handle multiple string formats, - including <CODE>IOR:</CODE>, - <CODE>corbaloc:</CODE>, - <CODE>corbaname:</CODE>, - and <CODE>file:</CODE>. - The application developer can - <A HREF="ior_parsing.html"> - add new IOR formats - </A> - using this option. - </TD> -</TR> -<TR> - <TD><CODE>-ORBConnectionCachingStrategy</CODE> <EM>type</EM></TD> - <TD><a name="-ORBConnectionCachingStrategy"></a> - <FONT COLOR=RED>This option is <STRONG>deprecated</STRONG>. Use - -ORBConnectionPurgingStrategy instead.</FONT> - </TD> -</TR> -<TR> - <TD><CODE>-ORBConnectionPurgingStrategy</CODE> <EM>type</EM></TD> - <TD><a name="-ORBConnectionPurgingStrategy"></a> - Opened connections are added to the transport cache so they can be - reused. However, if a process continues to run and these - connections are not reused, the cache will continue to grow. - Therefore, before each new connection, 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 others LFU (Least - Frequently Used), FIFO (First In First Out), and null (No connections - are purged) are contained within the TAO Strategies library. - </TD> -</TR> -<TR> - <TD><CODE>-ORBConnectionCacheMax</CODE> <EM>limit</EM></TD> - <TD><a name="-ORBConnectionCacheMax"></a> - 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. - </TD> -</TR> -<TR> - <TD><CODE>-ORBMuxedConnectionMax</CODE> <EM>number</EM></TD> - <TD><a name="-ORBMuxedConnectionMax"></a> - 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 options is more useful for - transports using a muxed connection strategy and want control on - the number of connections that are created by the active threads. - </TD> -</TR> -<TR> - <TD><CODE>-ORBConnectionCachePurgePercentage</CODE> <EM>percent</EM></TD> - <TD><a name="-ORBConnectionCachePurgePercentage"></a> - If the transport cache is purged, the specified percentage (20 by - default) of the total number of connections cached will be closed. - </TD> -</TR> -<TR> - <TD><CODE>-ORBPurgePercentage</CODE> <EM>percent</EM></TD> - <TD><a name="-ORBPurgePercentage"></a> - This option is deprecated and will automatically forward to - -ORBConnectionCachePurgePercentage. - </TD> -</TR> -<TR> - <TD><CODE>-ORBConnectionCacheLock</CODE> <EM>locktype</EM></TD> - <TD><a name="-ORBConnectionCacheLock"></a> - Specify the type of lock to be used by the Connection - Cache. Possible values for lock type are <code>thread</code>, which specifies - that an inter-thread mutex is used to guarantee exclusive - access, and <code>null</code>, which specifies that no locking be - performed. The default is thread. - </TD> -</TR> + <TD>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. </TD></TR> + <TR> + <TD><CODE>-ORBProtocolFactory</CODE> <EM>factory</EM></TD> + <TD><A name=-ORBProtocolFactory></A>Specify which pluggable protocol + factory to load. By default, only the factory for the IIOP protocol + (<CODE>IIOP_Factory</CODE> is loaded. + <P>For example, if some protocol called <EM><CODE>Foo</CODE></EM> whose + factory was called <EM><CODE>Foo_Factory</CODE></EM> was available, then + it could be loaded into TAO by specifying <CODE>-ORBProtocolFactory + Foo_Factory</CODE> in the service configurator file. The + <EM><CODE>Foo</CODE></EM> pluggable protocol would then be available for + use. </P></TD></TR> + <TR> + <TD><CODE>-ORBIORParser</CODE> <EM>parser</EM></TD> + <TD><A name=-ORBIORParser></A>Name an IOR Parser to load. IOR Parsers are + used to interpret strings passed to <CODE>ORB::string_to_object()</CODE>. + By default the ORB can handle multiple string formats, including + <CODE>IOR:</CODE>, <CODE>corbaloc:</CODE>, <CODE>corbaname:</CODE>, and + <CODE>file:</CODE>. The application developer can <A + href="http://cvs.doc.wustl.edu/viewcvs.cgi/*checkout*/TAO/docs/ior_parsing.html?rev=HEAD">add + new IOR formats </A>using this option. </TD></TR> + <TR> + <TD><CODE>-ORBConnectionPurgingStrategy</CODE> <EM>type</EM></TD> + <TD><A name=-ORBConnectionPurgingStrategy></A>Opened connections are added + to the transport cache so they can be reused. However, if a process + continues to run and these connections are not reused, the cache will + continue to grow. Therefore, before each new connection, 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 others LFU (Least Frequently + Used), FIFO (First In First Out), and null (No connections are purged) are + contained within the TAO Strategies library. </TD></TR> + <TR> + <TD><CODE>-ORBConnectionCacheMax</CODE> <EM>limit</EM></TD> + <TD><A name=-ORBConnectionCacheMax></A>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. </TD></TR> + <TR> + <TD><CODE>-ORBMuxedConnectionMax</CODE> <EM>number</EM></TD> + <TD><A name=-ORBMuxedConnectionMax></A>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. </TD></TR> + <TR> + <TD><CODE>-ORBConnectionCachePurgePercentage</CODE> <EM>percent</EM></TD> + <TD><A name=-ORBConnectionCachePurgePercentage></A>If the transport cache + is purged, the specified percentage (20 by default) of the total number of + connections cached will be closed. </TD></TR> + <TR> + <TD><CODE>-ORBConnectionCacheLock</CODE> <EM>locktype</EM></TD> + <TD><A name=-ORBConnectionCacheLock></A>Specify the type of lock to be + used by the Connection Cache. Possible values for lock type are + <CODE>thread</CODE>, which specifies that an inter-thread mutex is used to + guarantee exclusive access, and <CODE>null</CODE>, which specifies that no + locking be performed. The default is thread. </TD></TR> <TR> <TD><CODE>-ORBCorbaObjectLock</CODE> <EM>locktype</EM></TD> <TD><a name="-ORBCorbaObjectLock"></a> @@ -585,7 +764,7 @@ would load all the options listed within "". values for lock type are <code>thread</code>, which specifies that an inter-thread mutex is used to guarantee exclusive access, and <code>null</code>, which specifies that no locking - be performed. The default is thread. + be performed. The default is thread. The <code>null</code> lock option is useful when there is only one thread in the system. This option can be used to minimize @@ -606,536 +785,329 @@ would load all the options listed within "". <code>thread</code>, which specifies that an inter-thread mutex is used to guarantee exclusive access, and <code>null</code>, which specifies that no locking be performed. The default is - thread. + thread. </TD> </TR> -<TR> - <TD><CODE>-ORBFlushingStrategy</CODE> <EM>type</EM></TD> - <TD><a name="-ORBFlushingStrategy"></a> - By default TAO provides three strategies to flush queued - messages. - The <CODE>leader_follower</CODE> 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 <CODE>reactive</CODE> 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 <CODE>blocking</CODE> strategy flushes the - queue as soon as it becomes "full", and blocks the - thread until all the data is sent. - </TD> -</TR> -<TR> - <TD><CODE>-ORBNativeCharCodeset</CODE> <EM>id</EM></TD> - <TD><a name="-ORBNativeCharCodeset"></a> - Specify the codeset ID used natively to represent char data. The - ID value may be a number or a Locale name. The codeset ID is a - 32-bit unsigned value that is assigned by the Open Systems Foundation, - and listed in the OSF's Code and Character Set registry. In TAO, this - registry is embedded in an ACE class, ACE_Codeset_Registry. The file - ace/Codeset_Registry_db.cpp composes an array of those codesets applications - linked to it may use. The full code and character set registry currently - lists over two hundred specific codesets. The tool <CODE>bin/mkcsregdb</CODE> - may be used to generate a new Codeset_Registry_db.cpp file tuned to your - environment. If a Locale name is used, it must match a name entered in the - generated Codeset Registry db. As provided by the OSF, the registry does - not include Locale names, as these are not regulated. The default value - for the native Char codeset corresponds to the ISO-8859-1 (ASCII) codeset. - </TD> -</TR> -<TR> - <TD><CODE>-ORBNativeWcharCodeset</CODE> <EM>id</EM></TD> - <TD><a name="-ORBNativeWcharCodeset"></a> - Specify the codeset ID used natively to represent wide char data. The - ID value may be a number or a Locale name. The same rules apply to the - Wchar native codeset ID as do to the native Char codeset, with one exception. - No default value is defined for Wchar codesets, as required by the CORBA (2.3) - specification. If no Wchar codeset is defined, and communication is attempted - using wchar data, an exception is raised. - </TD> -</TR> -<TR> - <TD><CODE>-ORBCharCodesetTranslator</CODE> <EM>FactoryName</EM></TD> - <TD><a name="-ORBCharCodesetTranslator"></a> - Identify a factory used to supply translators between the native Char - codeset and some other codeset. The factory must be loaded as a separate - service object. Only the factories that match the configured native Wchar - codeset will actually be used. - </TD> -</TR> -<TR> - <TD><CODE>-ORBWcharCodesetTranslator</CODE> <EM>FactoryName</EM></TD> - <TD><a name="-ORBWcharCodesetTranslator"></a> - Identify a factory used to supply translators between the native Wchar - codeset and some other codeset. The factory must be loaded as a separate - service object. Only the factories that match the configured native Wchar - codeset will actually be used. - </TD> -</TR> -</TABLE> -</P> -</blockquote> -<HR><H3><A NAME="DefaultServer"></A><CODE>TAO_Default_Server_Strategy_Factory</CODE></H3> + <TR> + <TD><CODE>-ORBFlushingStrategy</CODE> <EM>type</EM></TD> + <TD><A name=-ORBFlushingStrategy></A>By default TAO provides three + strategies to flush queued messages. The <CODE>leader_follower</CODE> + 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 <CODE>reactive</CODE> 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 + <CODE>blocking</CODE> strategy flushes the queue as soon as it becomes + "full", and blocks the thread until all the data is sent. +</TD></TR></TBODY></TABLE></P> +<BLOCKQUOTE></BLOCKQUOTE> -<blockquote> -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) +<h5><A name=TARF>(b). Advanced_Resource_Factory</A></h5> -<p><code>static Server_Strategy_Factory "[list of options]"</code></p> -would load all the options listed within "" +This factory is located in the <CODE>TAO_Strategies</CODE> library. It +accepts the options below as well as those described above in the +<CODE>Resource_Factory</CODE>. This factory can be loaded +dynamically using a service configurator directive of the form (all on +one line): <P> -<p><em>Note:</em> <code>-ORBDemuxStrategy</code> flag has been changed to <code>-ORBSystemidPolicyDemuxStrategy</code> and <code>-ORBUseridPolicyDemuxStrategy</code>. -<p><em>Note:</em> <code>-ORBTableSize</code> flag has been changed to <code>-ORBActiveObjectMapSize</code>. +<CODE>dynamic Advanced_Resource_Factory Service_Object +*</CODE><BR><CODE>TAO_Strategies:_make_TAO_Advanced_Resource_Factory +() "-ORBReactorType select_st" </CODE><P> +It can also be loaded statically by doing the following:<BR> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <TR> +<UL> + <LI>Add <CODE>#include "tao/Strategies/advanced_resource.h"</CODE> to the file + containing <CODE>main()</CODE>. + <LI>Link the TAO_Strategies library into the executable. + <LI>Specify a service configurator directive of the form: <CODE>static + Advanced_Resource_Factory "-ORBReactorType select_st"</CODE> </LI></UL>You can +omit the <CODE>#include</CODE> if you always use dynamic libraries.<P> + +Loading the <CODE>Advanced_Resource_Factory</CODE> disables the +<CODE>Resource_Factory</CODE>. Any directives for the +<CODE>Resource_Factory</CODE> will have no effect (and +generate warnings telling you so). The following table lists the +options that can be provided in double quotes. <A +href="http://cvs.doc.wustl.edu/viewcvs.cgi/TAO/performance-tests/Latency/Single_Threaded/svc.conf?rev=HEAD"> + This </A> shows how to specify this option in the svc.conf file.<P> - <TD><a name="orb_concurrency"><CODE>-ORBConcurrency</CODE></a> - <EM>which</EM></TD> - <TD>Specify which - concurrency strategy to use. Range of values is <code>reactive</code> - for a purely Reactor-driven concurrency strategy or - <code>thread-per-connection</code> for creating a new thread to - service each connection. The default is reactive. - </TD> - </TR> +<BLOCKQUOTE> + <P> + <TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> + <TR> + <TH>Option</TH> + <TH>Description</TH></TR> + <TR> + <TD><CODE>-ORBReactorType</CODE> <EM>which</EM></TD> + <TD><A name=-ORBReactorType></A>Specify what kind of reactor the ORB + uses. The default reactor is the ACE_TP_Reactor. + <TABLE cellSpacing=2 cellPadding=0 border=1> + <TBODY> + <TR> + <TH><EM>which</EM></TH> + <TH>Reactor</TH></TR> + <TR> + <TD><CODE>select_mt</CODE></TD> + <TD>Use the multi-thread select-based reactor.</TD></TR> + <TR> + <TD><CODE>select_st</CODE></TD> + <TD>Use the single-thread select-based reactor.</TD></TR> + <TR> + <TD><CODE>fl</CODE></TD> + <TD>Use the FLReactor (FLTK-based).</TD></TR> + <TR> + <TD><CODE>wfmo</CODE></TD> + <TD>Use the WFMO reactor (Win32 only).</TD></TR> + <TR> + <TD><CODE>msg_wfmo</CODE></TD> + <TD>Use the MsgWFMO reactor (Win32 only).</TD></TR> + <TR> + <TD><CODE>tp</CODE></TD> + <TD>Use the <CODE>ACE_TP_Reactor</CODE>, a select based + thread-pool reactor which is the +default.</TD></TR></TBODY></TABLE></TD></TR> + <TR> + <TD><CODE>-ORBReactorThreadQueue</CODE> <EM>which</EM></TD> + <TD><A name=-ORBReactorThreadQueue></A>Applies only to the + ACE_TP_Reactor, i.e., when <CODE>-ORBReactorType</CODE> = + <CODE>tp</CODE>, and specifies the order, last-in-first-out + (<EM>which</EM> = <CODE>LIFO</CODE>), the default, or first-in-first-out + (<EM>which</EM> = <CODE>FIFO</CODE>), in which waiting threads are + selected to run by the ACE_Select_Reactor_Token. </TD></TR> + <TR> + <TD><CODE>-ORBInputCDRAllocator</CODE> <EM>which</EM></TD> + <TD><A name=-ORBInputCDRAllocator></A>Specify whether the ORB uses + locked (<EM>which</EM> = <CODE>thread</CODE>) or lock-free + (<EM>which</EM> = <CODE>null</CODE>) allocators for the incoming CDR + buffers. Though <CODE>null</CODE> should give the optimal performance; + we made the default <CODE>thread</CODE>. 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. + </TD></TR> + <TR> + <TD><CODE>-ORBReactorRegistry</CODE> <EM>registry_type</EM></TD> + <TD><A name=-ORBReactorRegistry></A>This option is no longer supported. + The Advanced Resource Factory will emit an error if you attempt its use. + </TD></TR></TBODY></TABLE></P></BLOCKQUOTE> + +<!-- Doug, Bala2 - I gave generic name here - Andy --> +<h4><A name=TSSF>3. Server_Strategy_Factory</A></h4> + +Certain elements of the ORB relate only to server side behavior. 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 demultiplexing and concurrency-related 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 +<CODE>Server_Strategy_Factory</CODE> <p> +<!-- Doug, Bala2 - I added the above line - Andy --> + +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)<P><CODE>static Server_Strategy_Factory "[list of +options]"</CODE><P>would load all the options listed within "". This +<A +href="http://cvs.doc.wustl.edu/viewcvs.cgi/TAO/performance-tests/Latency/Single_Threaded/svc.conf?rev=HEAD"> file</A> shows how to specify this option in the svc.conf file. +<p> + +<TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> <TR> - - <TD><a name="server_timeout"><CODE>-ORBThreadPerConnectionTimeout</CODE></a> - <EM>milliseconds</EM></TD> - <TD>In many platforms it is impossible to interrupt the server - threads created by the - <code>thread-per-connection</code> model. - This is because these threads are blocked in - <CODE>read()</CODE> operations (and not in - <CODE>select()</CODE>). - 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 <CODE>INFINITE</CODE>. - - <P> - If the option is not provided then the ORB uses the - compile time flag - <CODE>TAO_DEFAULT_THREAD_PER_CONNECTION_TIMEOUT</CODE>, - this flag also expresses the time in milliseconds (as - a string constant) and the magic value - <CODE>"INFINITE"</CODE> can be used to disable polling - entirely. This yields a slight performance improvement - (around 1%). - </P> - </TD> - </TR> + <TH>Option</TH> + <TH>Description</TH></TR> + <TR> + <TD><A name=orb_concurrency><CODE>-ORBConcurrency</CODE></A> + <EM>which</EM></TD> + <TD>Specify which concurrency strategy to use. Range of values is + <CODE>reactive</CODE> for a purely Reactor-driven concurrency strategy or + <CODE>thread-per-connection</CODE> for creating a new thread to service + each connection. The default is reactive. </TD></TR> + <TR> + <TD><A name=server_timeout><CODE>-ORBThreadPerConnectionTimeout</CODE></A> + <EM>milliseconds</EM></TD> + <TD>In many platforms it is impossible to interrupt the server threads + created by the <CODE>thread-per-connection</CODE> model. This is because + these threads are blocked in <CODE>read()</CODE> operations (and not in + <CODE>select()</CODE>). 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 + <CODE>INFINITE</CODE>. + <P>If the option is not provided then the ORB uses the compile-time flag + <CODE>TAO_DEFAULT_THREAD_PER_CONNECTION_TIMEOUT</CODE>, this flag also + expresses the time in milliseconds (as a string constant) and the magic + value <CODE>"INFINITE"</CODE> can be used to disable polling entirely. + This yields a slight performance improvement (around 1%). </P></TD></TR> <TR> <TD><CODE>-ORBActiveObjectMapSize</CODE> <EM>active object map - size</EM></TD> - <TD>Specify the size of the active object map. If not - specified, the default value is 64.</TD> - </TR> +size</EM></TD> + <TD>Specify the size of the active object map. If not specified, the + default value is 64.</TD></TR> <TR> - - <TD><CODE>-ORBUseridPolicyDemuxStrategy</CODE> <EM>user id policy - based demultiplexing strategy</EM></TD> - <TD>Specify the demultiplexing - lookup strategy to be used with the user id policy. The - <EM>demultiplexing strategy</EM> can be one of <CODE>dynamic</CODE> or - <CODE>linear</CODE>. This option defaults to use the - <CODE>dynamic</CODE> strategy. </TD> - </TR> + <TD><CODE>-ORBUseridPolicyDemuxStrategy</CODE> <EM>user id policy based + demultiplexing strategy</EM></TD> + <TD>Specify the demultiplexing lookup strategy to be used with the user id + policy. The <EM>demultiplexing strategy</EM> can be one of + <CODE>dynamic</CODE> or <CODE>linear</CODE>. This option defaults to using + the <CODE>dynamic</CODE> strategy. </TD></TR> <TR> - <TD><CODE>-ORBSystemidPolicyDemuxStrategy</CODE> <EM>system id policy - based demultiplexing strategy</EM></TD> - - <TD>Specify the demultiplexing lookup strategy to be used with the - system id policy. The <EM>demultiplexing strategy</EM> can be - one of <CODE>dynamic</CODE>, <CODE>linear</CODE>, or - <CODE>active</CODE>. This option defaults to use the - <CODE>dynamic</CODE> strategy when - <CODE>-ORBAllowReactivationOfSystemids</CODE> is true, and to - <CODE>active</CODE> strategy when - <CODE>-ORBAllowReactivationOfSystemids</CODE> is false. </TD> - - </TR> + based demultiplexing strategy</EM></TD> + <TD>Specify the demultiplexing lookup strategy to be used with the system + id policy. The <EM>demultiplexing strategy</EM> can be one of + <CODE>dynamic</CODE>, <CODE>linear</CODE>, or <CODE>active</CODE>. This + option defaults to use the <CODE>dynamic</CODE> strategy when + <CODE>-ORBAllowReactivationOfSystemids</CODE> is true, and to + <CODE>active</CODE> strategy when + <CODE>-ORBAllowReactivationOfSystemids</CODE> is false. </TD></TR> <TR> - <TD><CODE>-ORBUniqueidPolicyReverseDemuxStrategy</CODE> <EM>unique id - policy based reverse demultiplexing strategy</EM></TD> - <TD>Specify the - reverse demultiplexing lookup strategy to be used with the unique id - policy. The <EM>reverse demultiplexing strategy</EM> can be one of - <CODE>dynamic</CODE> or <CODE>linear</CODE>. This option defaults to - use the <CODE>dynamic</CODE> strategy. </TD> - </TR> + policy based reverse demultiplexing strategy</EM></TD> + <TD>Specify the reverse demultiplexing lookup strategy to be used with the + unique id policy. The <EM>reverse demultiplexing strategy</EM> can be one + of <CODE>dynamic</CODE> or <CODE>linear</CODE>. This option defaults to + using the <CODE>dynamic</CODE> strategy. </TD></TR> + <TR> + <TD><CODE>-ORBAllowReactivationOfSystemids</CODE> <EM>allows reactivation + of system ids</EM></TD> + <TD>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 + <CODE>ORBAllowReactivationOfSystemids</CODE> can be <CODE>0</CODE> or + <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD></TR> <TR> - - <TD><CODE>-ORBAllowReactivationOfSystemids</CODE> <EM>allows - reactivation of system ids</EM></TD> - <TD>Specify whether system ids - can be reactivated, i.e., once an id that was generated by the system - has be 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 - <CODE>ORBAllowReactivationOfSystemids</CODE> can be <CODE>0</CODE> or - <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD> - </TR> - <TR> - <TD><CODE>-ORBActiveHintInIds</CODE> <EM>adds an active hint in - ids</EM></TD> - <TD>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 - <CODE>-ORBAllowReactivationOfSystemids</CODE> is set to - <CODE>0</CODE>. The <EM>-ORBActiveHintInIds</EM> can be <CODE>0</CODE> - or <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD> - </TR> +ids</EM></TD> + <TD>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 + <CODE>if -ORBAllowReactivationOfSystemids</CODE> is set to <CODE>0</CODE>. + The <EM>-ORBActiveHintInIds</EM> can be <CODE>0</CODE> or <CODE>1</CODE>. + This option defaults to <CODE>1</CODE>. </TD></TR> <TR> - <TD><CODE>-ORBPoaMapSize</CODE> <EM>poa map size</EM></TD> - <TD>Specify - the size of the poa map. If not specified, the default value is - 24.</TD> - </TR> + <TD>Specify the size of the POA map. If not specified, the default value + is 24.</TD></TR> <TR> - - <TD><CODE>-ORBPersistentidPolicyDemuxStrategy</CODE> <EM>persistent - id policy based demultiplexing strategy</EM></TD> - <TD>Specify the - demultiplexing lookup strategy to be used with the persistent id - policy. The <EM>demultiplexing strategy</EM> can be one of - <CODE>dynamic</CODE> or <CODE>linear</CODE>. This option defaults to - use the <CODE>dynamic</CODE> strategy. </TD> - </TR> + <TD><CODE>-ORBPersistentidPolicyDemuxStrategy</CODE> <EM>persistent id + policy based demultiplexing strategy</EM></TD> + <TD>Specify the demultiplexing lookup strategy to be used with the + persistent id policy. The <EM>demultiplexing strategy</EM> can be one of + <CODE>dynamic</CODE> or <CODE>linear</CODE>. This option defaults to using + the <CODE>dynamic</CODE> strategy. </TD></TR> <TR> - <TD><CODE>-ORBTransientidPolicyDemuxStrategy</CODE> <EM>transient id - policy based demultiplexing strategy</EM></TD> - <TD>Specify the - demultiplexing lookup strategy to be used with the transient id - policy. The <EM>demultiplexing strategy</EM> can be one of - <CODE>dynamic</CODE>, <CODE>linear</CODE>, or - <CODE>active</CODE>. This option defaults to use the - <CODE>active</CODE> strategy. </TD> - </TR> + policy based demultiplexing strategy</EM></TD> + <TD>Specify the demultiplexing lookup strategy to be used with the + transient id policy. The <EM>demultiplexing strategy</EM> can be one of + <CODE>dynamic</CODE>, <CODE>linear</CODE>, or <CODE>active</CODE>. This + option defaults to using the <CODE>active</CODE> strategy. </TD></TR> <TR> - - <TD><CODE>-ORBActiveHintInPOANames</CODE> <EM>adds an active hint in - poa names</EM></TD> - <TD>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 - <EM>-ORBActiveHintInPOANames</EM> can be <CODE>0</CODE> or - <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD> - </TR> + <TD><CODE>-ORBActiveHintInPOANames</CODE> <EM>adds an active hint in poa + names</EM></TD> + <TD>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 <EM>-ORBActiveHintInPOANames</EM> can be <CODE>0</CODE> or + <CODE>1</CODE>. This option defaults to <CODE>1</CODE>. </TD></TR> <TR> - <TD><CODE>-ORBThreadFlags</CODE> <EM>thread flags</EM></TD> <TD>Specify the flags used for thread creation. Flags can be any - logical-OR combination of <CODE>THR_DETACHED</CODE>, - <CODE>THR_BOUND</CODE>, <CODE>THR_NEW_LWP</CODE>, - <CODE>THE_SUSPENDED</CODE>. The default is <CODE>THR_BOUND | - THR_DETACHED</CODE> . </TD> - </TR> + logical-OR combination of <CODE>THR_DETACHED</CODE>, + <CODE>THR_BOUND</CODE>, <CODE>THR_NEW_LWP</CODE>, + <CODE>THE_SUSPENDED</CODE>. The default is <CODE>THR_BOUND | + THR_DETACHED</CODE> . </TD></TR> <TR> - <TD><CODE>-ORBPOALock</CODE> <EM>lock type</EM></TD> - <TD><a - name="-ORBPOALock"></a>Specify the type of lock to be used for POA - accesses. Possible values for <em>lock type</em> are - <code>thread</code>, which specifies that an inter-thread mutex is - used to guarantee exclusive access, and <code>null</code>, which - specifies that no locking be performed. The default is - <code>thread</code>.</TD> - </TR> -</TABLE> -</P> -</blockquote> - -<HR><H3><A NAME="DefaultClient"></A><CODE>TAO_Default_Client_Strategy_Factory</CODE></H3> + <TD><A name=-ORBPOALock></A>Specify the type of lock to be used for POA + accesses. Possible values for <EM>lock type</EM> are <CODE>thread</CODE>, + which specifies that an inter-thread mutex is used to guarantee exclusive + access, and <CODE>null</CODE>, which specifies that no locking be + performed. The default is <CODE>thread</CODE>.</TD></TR></TBODY></TABLE></P> + +<h4><A name=TCSF>5. Client_Strategy_Factory</A></h4> +Similar to the server strategy factory, the client strategy factory +supports those elements of TAO that are specific to the behavior of +clients (Any application that actively establishes connections, +submits requests and perhaps receive responses.). The client strategy +factory provides control over several resources used by clients. TAO +provides a default client strategy factory called +<CODE>Client_Strategy_Factory</CODE><p> -<BLOCKQUOTE> 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) +(svc.conf) file. The following line in the svc.conf file (all in one +line)<P><CODE>static Client_Strategy_Factory "[list of +options]"</CODE><P> would load all the options listed within "". This +<A +href="http://cvs.doc.wustl.edu/viewcvs.cgi/TAO/performance-tests/Latency/Single_Threaded/svc.conf?rev=HEAD"> + file</A> shows how to specify this option in the svc.conf file.<P> -<p><code>static Client_Strategy_Factory "[list of options]"</code></p> -would load all the options listed within "". - - -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > +<TABLE cellSpacing=2 cellPadding=0 border=2> + <TBODY> <TR> <TH>Option</TH> - <TH>Description</TH> - </TR> + <TH>Description</TH></TR> <TR> - <TD><CODE><a name="#-ORBProfileLock">-ORBProfileLock</a></CODE> <EM>which</EM></TD> - <TD> - Specify the kind of synchronization primitive for the - Profiles. - Default is <code>thread</code>, which means that a regular thread - mutex is used. The - second option is <code>null</code>, 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. - </TD> - </TR> + <TD><CODE><A name=#-ORBProfileLock>-ORBProfileLock</A></CODE> + <EM>which</EM></TD> + <TD>Specify the kind of synchronization primitive for the Profiles. + Default is <CODE>thread</CODE>, which means that a regular thread mutex is + used. The second option is <CODE>null</CODE>, 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. </TD></TR> <TR> <TD><CODE>-ORBClientConnectionHandler</CODE> <EM>MT / ST / RW</EM></TD> - - <TD><A name="-ORBClientConnectionHandler"></a> - - 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. <p> - - 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. <p> - - RW selects a strategy that simply blocks in recv() when waiting for a - response from the server instead of waiting in the Reactor. 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 AMI - calls. Therefore, this strategy is appropriate only for "pure" - synchronous clients. Note that applications with nested - upcalls are not "pure" synchronous clients. Also note - that this strategy will only effect 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. <p> - - Default for this option is MT. - - </TD> - </TR> - + <TD><A name=-ORBClientConnectionHandler></A>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. + <P>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. + <P>RW selects a strategy that simply blocks in recv() when waiting for a + response from the server instead of waiting in the Reactor. 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 AMI calls. Therefore, this strategy is appropriate + only for "pure" synchronous clients. Note that applications with nested + upcalls are not "pure" synchronous clients. Also note that this strategy + will only effect 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. + <P>Default for this option is MT. </P></TD></TR> <TR> <TD><CODE>-ORBTransportMuxStrategy</CODE> <EM>EXCLUSIVE / MUXED</EM></TD> - - <TD><A name="-ORBTransportMuxStrategy"></a> - - 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. <p> - - MUXED means that Transport multiplexes more than one request at the - same time on a connection. This option is often used in - conjunction with Asynchronous Method Invocation, because - multiple requests can be sent 'in bulk'. <p> - - Default for this option is MUXED. - - </TD> - </TR> - <TR> - <TD><CODE>-ORBConnectStrategy</CODE> <EM>type</EM></TD> - <TD><a name="-ORBConnectStrategy"></a> - TAO provides three strategies to connect to remote servers. - The default <CODE>leader_follower</CODE> 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 <CODE>reactive</CODE> 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 <CODE>blocked</CODE> - strategy as the name implies, blocks the thread until - connection is complete. Some of the protocols in TAO viz. SHMIOP - and SSLIOP can only use blocked strategy. - </TD> -</TR> -</TABLE> -</P> -</BLOCKQUOTE> - -<HR><H3><A NAME="AdvancedResourceFactory"></A><CODE>TAO_Advanced_Resource_Factory</CODE></H3> - -<p>This factory is located in the TAO_Strategies library. -It accepts the options below as well as those described above in the -<A HREF="#DefaultResourceFactory"><CODE>TAO_Default_Resource_Factory</CODE></A>. -This factory can be loaded dynamically using a service configurator -directive of the form (all on one line): -<p><code>dynamic Advanced_Resource_Factory Service_Object * TAO_Strategies:_make_TAO_Advanced_Resource_Factory () "-ORBReactorType select_st"</code> - -<p>It can also be loaded statically by doing the following: -<UL> - <LI>Add a <code>#include "tao/Strategies/advanced_resource.h"</code> to the file containing <code>main()</code> - <LI>Link the TAO_Strategies library into the executable - <LI>Specify a service configurator directive of the form: <code>static Advanced_Resource_Factory "-ORBReactorType select_st"</code> -</UL> -<p>You can omit the <code>#include</code> if you always use dynamic libraries. -<p>Once you have loaded the Advanced_Resource_Factory, then directives for the Resource_Factory have no effect (and generate warnings telling you so). -<p><em>Note:</em> <code>-ORBReactorLock</code> flag has been -superseded by <code><A HREF="#-ORBReactorType">-ORBReactorType</A></code>. - -<blockquote> -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> - <TR> - <TD><CODE>-ORBReactorType</CODE> <EM>which</EM></TD> - <TD><a name="-ORBReactorType"></a>Specify what kind of reactor the - ORB uses. The default reactor is the ACE_TP_Reactor. - <TABLE BORDER="1" CELLSPACING="2" CELLPADDING="0"> - <TR><TH><em>which</em></TH><TH>Reactor</TH> - </TR> - <TR> - <TD><CODE>select_mt</CODE></TD> - <TD>Use the multi-thread select-based reactor.</TD> - </TR> - - <TR> - <TD><CODE>select_st</CODE></TD> - <TD>Use the single-thread select-based reactor.</TD> - </TR> - - <TR> - <TD><CODE>fl</CODE></TD> - <TD>Use the FLReactor (FLTK-based).</TD> - </TR> - - <TR> - <TD><CODE>wfmo</CODE></TD> - <TD>Use the WFMO reactor (Win32 only).</TD> - </TR> - - <TR> - <TD><CODE>msg_wfmo</CODE></TD> - <TD>Use the MsgWFMO reactor (Win32 only).</TD> - </TR> - - <TR> - <TD><CODE>tp</CODE></TD> - <TD>Use the <CODE>ACE_TP_Reactor</CODE>, a select based - thread-pool reactor which is the default.</TD> - </TR> - </TABLE> - </TD> - </TR> - <TR> - <TD><CODE>-ORBReactorThreadQueue</CODE> <EM>which</EM></TD> - <TD><a name="-ORBReactorThreadQueue"></a> - Applies only to the ACE_TP_Reactor, i.e., when <CODE>-ORBReactorType</CODE> - = <CODE>tp</CODE>, and specifies the order, last-in-first-out - (<EM>which</EM> = <CODE>LIFO</CODE>), the default, or first-in-first-out - (<EM>which</EM> = <CODE>FIFO</CODE>), in which waiting threads are selected - to run by the ACE_Select_Reactor_Token. - </TD> - </TR> - <TR> - <TD><CODE>-ORBInputCDRAllocator</CODE> <EM>which</EM></TD> - <TD><a name="-ORBInputCDRAllocator"></a> - Specify whether the ORB uses locked - (<em>which</em> = <code>thread</code>) - or lock-free (<em>which</em> = <code>null</code>) - allocators for the incoming CDR buffers. - Though <CODE>null</CODE> should give the - optimal performance; - we made the default <CODE>thread</CODE>. - 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. - </TD> - </TR> - <TR> - <TD><CODE>-ORBReactorRegistry</CODE> <EM>registry_type</EM></TD> - <TD><a name="-ORBReactorRegistry"></a> - This option is no longer supported. The Advanced Resource - Factory will show an error if you attempt its use. - </TD> - </TR> -</TABLE> -</P> -</blockquote> - - - -<HR><H3><A NAME="RT_ORB_Loader"></A><CODE>RT_ORB_Loader</CODE></H3> - -<BLOCKQUOTE> - -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) - -<p><code>static RT_ORB_Loader "[list of options]"</code></p> -would load all the options listed within "". - -<P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0" > - <TR> - <TH>Option</TH> - <TH>Description</TH> - </TR> -<TR> - <TD><CODE>-ORBSchedPolicy</CODE> <EM>policy</EM></TD> - <TD><a name="-ORBSchedPolicy"></a> - Specify the scheduling policy used for the priority mapping - computations and to specify the scheduling policy used when - creating RTCORBA threads. - Priority mappings map the CORBA priority range (from 0 to 32767) - into the native OS priority range, but in some operating systems - the range depends on the scheduling policy used. - Valid values are <B>SCHED_OTHER</B>, <B>SCHED_FIFO</B> and - <B>SCHED_RR</B>. Defaults to <B>SCHED_OTHER</B>. Note that in - some operating systems some of - the scheduling policies require super user privileges. - </TD> -</TR> -<TR> - <TD><CODE>-ORBScopePolicy</CODE> <EM>scope</EM></TD> - <TD><a name="-ORBScopePolicy"></a> - Specify the scheduling scope used when creating RTCORBA threads. - Valid values are: <B>PROCESS</B> and <B>SYSTEM</B>. Defaults to - <B>PROCESS</B>. - </TD> -</TR> -<TR> - <TD><CODE>-ORBPriorityMapping</CODE> <EM>mapping_type</EM></TD> - <TD><a name="-ORBPriorityMapping"></a> - - Select the priority mapping to use. There are three priority - mappings provided by TAO: the <B>linear</B> mapping maps between - the CORBA range of priorities and the native range of - priorities; the <B>direct</B> mapping maps CORBA priorities - directly to native priorities; and the <B>continuous</B> maps - the first <i>n</i> CORBA priorities to the range of native - priorities, where <i>n</i> is the number of native priorities. - - Defaults to <B>direct</B>. Note that <B>continuous</B> was - previously referred to as <B>direct</B>. - - </TD> -</TR> - -</TABLE> -</P> -</BLOCKQUOTE> - -</blockquote> - -<P><HR><P> -Back to the TAO <A HREF="components.html">components documentation</A>. - -<!--#include virtual="/~schmidt/cgi-sig.html" --> -</HTML> + <TD><A name=-ORBTransportMuxStrategy></A><CODE>EXCLUSIVE</CODE> means that the + Transport does not multiplex requests on a connection. At a time, there + can be only one request pending on a connection. + <P><CODE>MUXED</CODE> means that Transport multiplexes more than one request at the + same time on a connection. This option is often used in conjunction with + Asynchronous Method Invocation (AMI), because multiple requests can be sent 'in + bulk'. + <P>Default for this option is <CODE>MUXED</CODE>. </P></TD></TR> + <TR> + <TD><CODE>-ORBConnectStrategy</CODE> <EM>type</EM></TD> + <TD><A name=-ORBConnectStrategy></A>TAO provides three strategies to + connect to remote servers. The default <CODE>leader_follower</CODE> + 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 <CODE>reactive</CODE> 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 <CODE>blocked</CODE> strategy as the name implies, blocks the + thread until connection is complete. Some of the protocols in TAO viz. + SHMIOP and SSLIOP can only use blocked strategy. +</TD></TR></TBODY></TABLE></P></BODY></HTML> |