TAO/docs/configurations.html

   1 <!--  -->
   2 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   3
   4 <html>
   5 <head>
   6 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   7 <meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; I) [Netscape]">
   8 <title>Configuring TAO's Components</title>
   9 </head>
  10
  11 <body text="#000000" bgcolor="#FFFFFF" link="#000FFF" vlink="#FF0F0F">
  12
  13 <hr>
  14 <h3>
  15 Configuring TAO's Components</h3>
  16
  17 <h3> Overview</h3>
  18
  19 <p> As described in the <a href="Options.html">options</a>
  20 documentation, various components in TAO can be customized by
  21 specifying options for those components.  This document illustrates
  22 how to combine these options to affect the behavior and performance of
  23 a TAO ORB, particularly its <a
  24 href="http://www.dre.vanderbilt.edu/~schmidt/PDF/CACM-arch.pdf">concurrency
  25 model</a>.  </p>
  26
  27 <p> TAO configures itself using the <a
  28 href="http://www.dre.vanderbilt.edu/~schmidt/PDF/Svc-Conf.pdf">ACE Service
  29 Configurator</a> framework.  Options are therefore specified using the
  30 <tt>svc.conf</tt> file (if you want to use a different file name, use
  31 the <tt><a href="Options.html#svcfonf">-ORBSvcConf</a></tt> option).
  32 Configurations selected via a <tt>svc.conf</tt> file are global
  33 <EM>per-process</EM>, e.g., all ORBs in a process will share the same
  34 concurrency model configured via a <code>svc.conf</code> file.  You
  35 can also setup default configurations for your programs.  Please see
  36 the <a href="#programming">Programming Considerations</a> for more
  37 detailed discussion on this.</p>
  38
  39 <hr>
  40 <h3>
  41 Roadmap</h3>
  42
  43 <blockquote>Details for the following configurations are provided.
  44 <ul>
  45   <li><b><a href="#comp">Configurating key components</a>:</b></li>
  46
  47       <ul>
  48         <li><a href="#concurrency">Server Concurrency Strategy.</a></li>
  49
  50         <li><a href="#orb">Number of ORBs.</a></li>
  51
  52         <!-- <li><a href="#orb_resources">ORB resources.</a></li> -->
  53
  54         <li><a href="#poa">POA.</a></li>
  55
  56         <li><a href="#coltbl">Collocation Table.</a></li>
  57
  58         <li><a href="#profile">Forwarding Profile</a></li>
  59
  60         <li><a href="#orbsvcs">orbsvcs Library</a></li>
  61       </ul>
  62
  63   <li>
  64       <b><a href="#examples">Configuration examples</a></b></li>
  65
  66       <ul>
  67         <li><a href="#reactive">Single-threaded, reactive model.</a></li>
  68
  69         <li><a href="#tpc">Multiple threads, single ORB, thread-per-connection
  70             model.</a></li>
  71
  72         <li><a href="#tpool">Multiple threads, single ORB, TAO thread-pool model.</a></li>
  73
  74         <li><a href="#rtpool">Multiple threads, single ORB, Real-time CORBA thread-pool model.</a></li>
  75
  76         <li><a href="#multiorb">Multiple threads, multiple ORBs,
  77             reactive model.</a></li>
  78
  79         <li><a href="#multiorb-tpc">Multiple threads, multiple ORBs,
  80             thread-per-connection model.</a></li>
  81
  82         <li><a href="#multiorb-tpool">Multiple threads,
  83             ORB-per-thread, thread-pool reactive model.</a></li>
  84
  85         <li>
  86             Each configuration has the following information:</li>
  87
  88             <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="70%">
  89               <tr>
  90                 <th align=left>Typical Use</th>
  91
  92                 <td>A brief description of the scenario and
  93                     its typical use.</td>
  94               </tr>
  95
  96               <tr>
  97                 <th align=left>Number of Threads</th>
  98
  99                 <td>The number of threads used by
 100                     ORB-related activities.</td>
 101               </tr>
 102
 103               <tr>
 104                 <th align=left>Thread Creator</th>
 105
 106                 <td>Identifies the creator of the threads
 107                     discussed above.</td>
 108               </tr>
 109
 110               <tr>
 111                 <th align=left>Thread task</th>
 112
 113                 <td>Describes what task is undertaken for
 114                     each thread.</td>
 115               </tr>
 116
 117               <tr>
 118                 <th align=left>Options</th>
 119
 120                 <td>Specifies the options for each service in order to
 121                     utilize this configuration.</td>
 122               </tr>
 123             </table>
 124       </ul>
 125
 126   <li><b><a href="#programming">Programming Considerations</a></b>
 127   <li><b><a href="#homogenous">Configuration for Homogenous Systems</a></b></li>
 128
 129       <ul>
 130         <li><a href="#homogenous_compile">Compile-time options</a></li>
 131
 132         <li><a href="#homogenous_runtime">Runtime-time</a></li>
 133       </ul>
 134   <li><b><a href="#suggestions">Configuration Suggestions</a></b>
 135 </ul>
 136 </blockquote>
 137
 138 <hr>
 139 <h3>
 140 <a NAME="comp"></a>Configuring Key ORB Components</h3>
 141
 142 <ul>
 143   <li><a name="orb"><b>Number of ORBs</b> -- </a></li>
 144       TAO can assign multiple endpoints to an ORB.
 145       It is therefore not necessary to create multiple ORBs to accept
 146       requests from multiple endpoints.  However, multiple ORBs can be
 147       used to support different policies within the same process,
 148       <EM>e.g.</EM>, handling requests in different thread
 149       priorities.  Multiple ORBs are most commonly used in the "ORB
 150       per-priority" pattern to avoid priority inversion in real-time
 151       systems. <p>
 152
 153   <li><a NAME="concurrency"></a><b>Server concurrency strategy</b> --
 154       The default server strategy factory provided by TAO supports two
 155       types of concurrency strategies that can be specified by adding
 156       the <tt>-ORBConcurrency</tt> flag in the <code><a
 157       href="Options.html#orb_concurrency">Server_Strategy_Factory</a></code>
 158       entry of the <code>svc.conf</code> file. This
 159       specifies the concurrency strategy an ORB uses.  This strategy
 160       is orthogonal to the number of ORBs or threads that are
 161       configured in a server process.  </li><P>
 162
 163       <ul>
 164         <li><tt>reactive</tt>: The ORB handles requests reactively,
 165             i.e., the ORB runs in one thread and service multiple
 166             requests/connections simultaneously using the
 167             <A
 168             HREF="http://www.dre.vanderbilt.edu/~schmidt/ACE-papers.html#reactor">
 169             ACE_Reactor</A>, which uses <tt>select</TT> or a similar
 170             event demultiplexing mechanism supported by the
 171             platform. </li> <P>
 172
 173         <li><tt>thread-per-connection</tt>: The ORB handles new
 174             connections by spawning a new thread whose job is to
 175             service requests coming from the connection.</li>
 176       </UL><P>
 177
 178   <li><a name="orb"><b>Thread Pools</b></a></li> --
 179       TAO supports several types of thread pools. <P>
 180
 181       <ul>
 182         <li><tt>reactive</tt>: In this approach, each thread
 183         in the thread pool has an ORB that accepts and processes
 184         requests reactively. This is also called as the
 185         "ORB-per-thread" model <P>
 186
 187         <li><P><tt>leader/followers</tt>: In this model, the user must
 188           create several threads, all of which invoke
 189           <CODE>ORB::run</CODE>, the ORB will select one of the threads
 190           to wait for incoming requests.
 191           This thread is called the leader thread and will process the
 192           first request that arrives to the ORB, but before
 193           doing so the ORB will selects another thread in the pool to
 194           become the leader.
 195           In other words the threads in the pool take turns to
 196           process the events.
 197         </p>
 198
 199         </li>
 200
 201       </UL><P>
 202
 203   <!--
 204   <li><a NAME="orb_resources"></a><b>ORB resources</b> --
 205
 206       <ul>
 207         <li><tt>global</tt>: All threads using the ORB access to
 208             the a set of global per-ORB resources. The same set of
 209             pre-ORB resources are shared by all threads accessing the
 210             ORB.  Notice that if you have more than one ORB, each ORB
 211             owns its own global resources.
 212
 213         <li><tt>tss</tt>: Each thread accessing an ORB gets its own
 214             set of thread-specific resources for the ORB.
 215
 216             <!-- @@ What about resource inheritance? - ->
 217       </ul><P></li> -->
 218
 219   <li><a NAME="coltbl"></a><b>Collocation Table</b> -- An ORB can have
 220       several listening endpoints.  If there are several ORBs in a
 221       process and a global collocation table is used, then all objects
 222       in the same process are considered collocated.  If not, only
 223       objects reside in the same <em>ORB</em> are considered
 224       collocated.  You can control the usage of global collocation
 225       table by passing the <code><a href="Options.html#-ORBCollocation">
 226       -ORBCollocation </a></code> flag as an argument of <code>
 227       ORB_init </code> (most often thru the command line flags.) <p>
 228
 229   <li> <a NAME="orbsvcs"></a><b>orbsvcs Library</b> --
 230       By default,
 231       TAO's Makefiles build all the services that TAO
 232       supports.
 233       To reduce build time you can exclude unused services,
 234       by defining the <tt>TAO_ORBSVCS</tt> makefile variable.
 235       We recommend using one of these two approaches:</li><P>
 236
 237       <ol>
 238         <li>In your
 239             <tt>$(ACE_ROOT)/include/makeinclude/platform_macros.GNU
 240             </tt> file,
 241
 242         <li>On the make command line, <i>e.g.</i>, <tt>make
 243             TAO_ORBSVCS=RTEvent</tt>, or
 244
 245         <li>Set (and export) a <tt>TAO_ORBSVCS</tt> environment variable.
 246       </ol><p>
 247
 248       Please see the <code><a
 249       href="../orbsvcs/orbsvcs/GNUMakefile">ORBSVCS
 250       Makefile</a></code> for the default setting of
 251       <code>TAO_ORBSVCS</code>.<p>
 252
 253       Please note that the Naming Service will always be built, even
 254       if Naming is not specified in <code>TAO_ORBSVCS</code>.  That's
 255       because many examples, tests, and presumably applications use it.<p>
 256 </ul>
 257
 258 <hr>
 259 <h3>
 260 <a NAME="examples"></a>Configuration Examples</h3>
 261
 262 The following are common ORB configurations used by TAO applications.<P>
 263
 264 <ul>
 265   <li>
 266       <a NAME="reactive"></a><B>Single-threaded, reactive model.</B></li> <P>
 267
 268       <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
 269         <tr>
 270           <th ALIGN=LEFT>Typical Use</th>
 271
 272           <td>This is the default configuration of TAO, where one
 273               thread handles requests from multiple clients via a
 274               one Reactor. It is appropriate when the requests (1)
 275               take a fixed, relatively uniform amount of time and (2)
 276               are largely compute bound.</td>
 277         </tr>
 278
 279         <tr>
 280           <th align=left>Number of Threads</th>
 281
 282           <td>1</td>
 283         </tr>
 284
 285         <tr>
 286           <th align=left>Thread Creator</th>
 287
 288           <td>OS or whoever creates the main ORB thread in a process.</td>
 289         </tr>
 290
 291         <tr>
 292           <th align=left>Thread task</th>
 293
 294           <td>The single thread processes all connection requests and
 295               CORBA messages.</td>
 296         </tr>
 297
 298         <tr>
 299           <th align=left>Synchronization considerations</th>
 300
 301           <td>Application servants needn't
 302               be concerned with synchronizing their interactions since
 303               there's only one thread active with this model.</td>
 304         </tr>
 305
 306         <tr>
 307           <th align=left>Options</th>
 308
 309           <td>The default settings should work just fine (by default,
 310               the <tt>-ORBReactorType</tt> is <tt>tp</tt>).  However,
 311               you can apply the following options to improve performance:<br>
 312               <tt>TAO_Advanced_Resource_Factory</tt>: <tt>-ORBReactorType
 313               select_st</tt>, <tt>-ORBInputCDRAllocator null</tt>
 314               <br><tt>TAO_Server_Strategy_Factory</tt>:
 315               <tt>-ORBconcurrency reactive</tt> (default),
 316               <br><tt>TAO_Client_Strategy_Factory</tt>:
 317               <tt>-ORBConnectorLock null</tt></td>
 318           </td>
 319         </tr>
 320       </table>
 321
 322       <P>Check out the <tt><a href="../examples/Simple/grid/">Grid</a></tt>
 323       for an example of a default configuration and
 324       <tt><a href="../performance-tests/Latency/Single_Threaded/">this</a></tt>
 325       for an example of settings that would provide better performance.
 326
 327       <P>
 328
 329   <li> <a NAME="tpc"></a><B>Multiple threads, single ORB, thread-per-connection
 330       model.</B></li> <P>
 331
 332       <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
 333         <tr ALIGN="LEFT">
 334         <th align=left>Typical Use
 335         </th>
 336
 337         <td>This configuration spawns a new thread to serve requests
 338             from a new connection. This approach works well when
 339             there are multiple connections active simultaneously and
 340             each request-per-connection may take a fair amount of
 341             time to execute.
 342         </td>
 343       </tr>
 344
 345       <tr>
 346         <th align=left>Number of Threads</th>
 347
 348         <td>1 thread for the ORB, plus 1 thread for each connection.</td>
 349       </tr>
 350
 351       <tr>
 352         <th align=left>Thread Creator</th>
 353
 354         <td>Programmer must set up the main thread which the ORB
 355             lives.  The ORB is responsible to create new threads upon
 356             new connections.</td>
 357       </tr>
 358
 359       <tr>
 360         <th align=left>Thread task</th>
 361
 362         <td>The main thread handles new connections and spawns new
 363             threads for them. Other threads handle requests for
 364             established connections.</td>
 365       </tr>
 366
 367         <tr>
 368           <th align=left>Synchronization considerations</th>
 369
 370           <td> To avoid race conditions, application servants may need to
 371             synchronize their methods if multiple clients can access
 372             them concurrently.</td>
 373         </tr>
 374
 375       <tr>
 376         <th align=left>Options</th>
 377
 378         <td><tt>TAO_Server_Strategy_Factory</tt>:
 379             <tt>-ORBConcurrency thread-per-connection</tt></td>
 380       </tr>
 381     </table>
 382     <P>
 383     <tt><a href="../performance-tests/Cubit/TAO/IDL_Cubit/">IDL_Cubit</a></tt>
 384     is a good example on using <i>multiple threads, thread-per-connection</i>
 385     configuration.<P>
 386
 387 <li>
 388     <a NAME="tpool"></a><B>Multiple threads, single ORB, TAO thread-pool model.</B></li><P>
 389
 390     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
 391       <tr>
 392         <th align=left>Typical Use</th>
 393
 394         <td>This model implements a highly optimized, TAO-specific thread pool that minimizes
 395             context switching and thread creation costs.  In this
 396             model, the programmer is responsible of spawning a group
 397             of threads, creating an ORB instance, and then instructing all the
 398             threads to run the ORB event loop.  When a request comes in, one
 399             of these waiting threads in the pool will handle the
 400             request.</td>
 401       </tr>
 402
 403       <tr>
 404         <th align=left>Number of Threads</th>
 405
 406         <td>Thread for the ORB, plus the number of threads used by the thread pool.</td>
 407       </tr>
 408
 409       <tr>
 410         <th align=left>Thread Creator</th>
 411
 412         <td>Pre-spawned by the main thread.</td>
 413       </tr>
 414
 415       <tr>
 416         <th align=left>Thread task</th>
 417
 418         <td>Blocking on the reactor to wait for its turn to handle a request.</td>
 419       </tr>
 420
 421         <tr>
 422           <th align=left>Synchronization considerations</th>
 423
 424           <td> To avoid race conditions, application servants may need to
 425             synchronize their methods if multiple clients or multiple
 426               thread from the same client can access
 427             them concurrently.</td>
 428         </tr>
 429
 430       <tr>
 431         <th align=left>Options</th>
 432
 433         <td> The default ORB settings support this concurrency
 434             configuration, though you'll need to spawn the extra
 435             threads in the pool explicitly.</td>
 436       </tr>
 437     </table>
 438     <P>
 439     <tt><a href="../tests/MT_Server">MT_Server</a></tt> is a good
 440     example on using <i>multiple threads, single ORB, TAO thread-pool</i>
 441     configuration.<P>
 442 <P>
 443
 444 <li>
 445     <a NAME="rtpool"></a><B>Multiple threads, single ORB, Real-time
 446     CORBA thread-pool model.</B></li><P>
 447
 448     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
 449       <tr>
 450         <th align=left>Typical Use</th>
 451
 452         <td>This model implements a highly optimized <A HREF="rtcorba/">Real-time CORBA</A> thread pool that minimizes
 453             context switching, and thread creation costs.  In this
 454             model, the application is responsible for starting up the ORB and then
 455             calling the Real-time CORBA thread pool factory methods that
 456             internally spawn a pool of threads.  When a request comes in, one
 457             of these waiting threads in the pool will handle the
 458             request in accordance with the various CORBA policies.</td>
 459       </tr>
 460
 461       <tr>
 462         <th align=left>Number of Threads</th>
 463
 464         <td>Thread for the ORB, plus the number of threads used by the thread pool.</td>
 465       </tr>
 466
 467       <tr>
 468         <th align=left>Thread Creator</th>
 469
 470         <td>Static threads are pre-spawned by the ORB, which also
 471             spawns any dynamic threads on-demand.</td>
 472       </tr>
 473
 474       <tr>
 475         <th align=left>Thread task</th>
 476
 477         <td>Blocking on the reactor to wait for its turn to handle a request.</td>
 478       </tr>
 479
 480         <tr>
 481           <th align=left>Synchronization considerations</th>
 482
 483           <td> To avoid race conditions, application servants may need to
 484             synchronize their methods if multiple clients or multiple
 485               thread from the same client can access
 486             them concurrently.</td>
 487         </tr>
 488
 489       <tr>
 490         <th align=left>Options</th>
 491
 492         <td> The ORB must be configured to work with <A
 493             HREF="rtcorba">Real-time CORBA</A>, at which point the
 494             default settings work fine.</td>
 495       </tr>
 496     </table>
 497     <P>
 498     <tt><a href="../tests/RTCORBA/Thread_Pool">Thread_Pool</a></tt> is a good
 499     example on using <i>multiple threads, single ORB, Real-time CORBA thread-pool</i>
 500     configuration.<P>
 501 <P>
 502
 503 <li>
 504     <P><B>Multiple threads, multiple ORBs, reactive model.</B><a NAME="multiorb"></a></li><P>
 505
 506     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%">
 507       <tr>
 508         <th align=left>Typical Use</th>
 509
 510         <td>In this configuration, there are multiple ORBs in a
 511             process with multiple threads. Each thread handles requests
 512             reactively.  This model is good for hard real-time applications that
 513             require different thread priorities for the various
 514             ORBs.</td>
 515       </tr>
 516
 517       <tr>
 518         <th align=left>Number of Threads</th>
 519
 520         <td>One thread for each ORB.</td>
 521       </tr>
 522
 523       <tr>
 524         <th align=left>Thread Creator</th>
 525
 526         <td>The main process (thread).</td>
 527       </tr>
 528
 529       <tr>
 530         <th align=left>Thread task</th>
 531
 532         <td>Service the requests from associating ORB.</td>
 533       </tr>
 534
 535         <tr>
 536           <th align=left>Synchronization considerations</th>
 537
 538           <td>Application servants needn't
 539               be concerned with synchronizing their interactions if
 540               there's no cross ORB/thread access.</td>
 541         </tr>
 542
 543       <tr>
 544         <th align=left>Options</th>
 545
 546         <td> The default settings just works fine. However, one could
 547             use  <br><tt>TAO_Advanced_Resource_Factory</tt>: <tt>-ORBReactorType
 548             "<em>which</em>"</tt>, for a thread-safe platform-specific reactor.<br>
 549             </td>
 550       </tr>
 551 </table>
 552 <P>
 553
 554 <li><B>Multiple threads, multiple ORBs, thread-per-connection model.</B><a
 555     NAME="multiorb-tpc"></a></li><P>
 556
 557     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%">
 558       <tr align="left">
 559       <th align=left>Typical Use
 560       </th>
 561
 562       <td>This approach provides a range of thread priorities plus connections
 563           that don't interfere with each others.</td>
 564     </tr>
 565
 566     <tr>
 567       <th align=left>Number of Threads</th>
 568
 569       <td>One thread for each ORB, plus one thread for each connection.</td>
 570     </tr>
 571
 572     <tr>
 573       <th align=left>Thread Creator</th>
 574
 575       <td>Main threads creates threads running ORBs. They, in turns,
 576           create connection handling threads.</td>
 577     </tr>
 578
 579     <tr>
 580       <th align=left>Thread task</th>
 581
 582       <td>There are threads running ORB's event loops which handle
 583           connection requests and handler threads which service
 584           requests from established connections.</td>
 585     </tr>
 586
 587         <tr>
 588           <th align=left>Synchronization considerations</th>
 589
 590           <td> To avoid race conditions, application servants may need to
 591             synchronize their methods if multiple clients can access
 592             them concurrently.</td>
 593         </tr>
 594
 595     <tr>
 596       <th align=left>Options</th>
 597
 598       <td><tt>TAO_Server_Strategy_Factory</tt>:
 599           <tt>-ORBConcurrency thread-per-connection</tt></td>
 600     </tr>
 601 </table>
 602
 603 <P>
 604 <tt><a href="../performance-tests/Cubit/TAO/MT_Cubit/">MT_Cubit</a>
 605 </tt> is a good example on using <i>multiple threads,
 606 multiple ORBs, and thread-per-connection</i> configuration.<P>
 607
 608 <li>
 609     <B>Multiple threads, multiple ORBs, thread-pool model.</B><a NAME="multiorb-tpool"></a>
 610 </li><P>
 611
 612     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
 613       <tr>
 614         <th align=left>Typical Use</th>
 615
 616         <td>This model incorporates the advantage of using thread-pool
 617             while allowing hard real-time system to handle requests in
 618             different priority.</td>
 619       </tr>
 620
 621       <tr>
 622         <th align=left>Number of Threads</th>
 623
 624         <td>One thread for each ORB, plus the total number of threads in all thread pools</td>
 625       </tr>
 626
 627       <tr>
 628         <th align=left>Thread Creator</th>
 629
 630         <td>Pre-spawned by the main thread.</td>
 631       </tr>
 632
 633       <tr>
 634         <th align=left>Thread task</th>
 635
 636         <td>Handle incoming request for the ORB event loop it is
 637             waiting on.</td>
 638       </tr>
 639
 640         <tr>
 641           <th align=left>Synchronization considerations</th>
 642
 643           <td>Application servants needn't
 644               be concerned with synchronizing their interactions if
 645               there's no cross ORB/thread access.</td>
 646         </tr>
 647
 648       <tr>
 649         <th align=left>Options</th>
 650
 651         <td> The default settings work well for this</td>
 652       </tr>
 653 </table>
 654 </ul>
 655
 656 <hr>
 657 <h3>
 658 Programming Considerations<a NAME="programming"></a></h3>
 659
 660 There are several ways to pass option flags into TAO's
 661 components. <P>
 662
 663 <ul>
 664
 665   <li><p>The plain vanilla approach is do nothing.  All TAO components
 666       use their <a
 667       href="Options.html">default settings</A>.</p>
 668
 669   <li><p>The most common use case is to use a file called
 670       <code>svc.conf</code>.  On most platforms, TAO programs
 671       automatically search and read in the file.  The disadvantage of
 672       this approach is you always need a <code>svc.conf</code> file if
 673       you want to do use non-default configuration.</p>
 674
 675   <li><p>You can use <code>-ORBSvcConf <em>filename</em></code> to use
 676       a config file that is not called <code>svc.conf</code>.
 677       Specifying <code>-ORBSvcConf</code> exclude the reading of
 678       default <code>svc.conf</code> file.</p>
 679
 680   <li><p>If you don't want the application users to worry about
 681       setting up or knowing about <code>svc.conf</code> files, you can
 682       call <code>TAO::ORB::default_svc_conf_entries()</code>
 683       before calling the first <code>ORB_init()</code> in your program
 684       to set up the default svc.conf entries.  In this case, if a TAO
 685       application cannot find a svc.conf file, it will configure TAO's
 686       components using the default settings.  You can still use a
 687       <code>svc.conf</code> file or use <code>-ORBSvcConf</code>
 688       option to tune the program.<P>
 689
 690   <li><p>TAO programs evaluate the configuration settings in the following
 691       order:</p>
 692
 693       <ol>
 694         <li>File specified in <code>-ORBSvcConf</code> command-line
 695             option, if one exist.  Otherwise, the
 696             <code>svc.conf</code> in the start-up directory will be
 697             evaluated, if one exist.
 698         <li>Default entries set by
 699             <code>TAO::ORB::default_svc_conf_entries()</code>, if
 700             ones exist.
 701         <li>Default configuration as specified in <a
 702             href="Options.html">this document</a>.
 703       </ol>
 704
 705       <p>Notice that the first encountered component settings are
 706       always the ones take effect.  For example, if you set the entries
 707       for <code>Resource_Factory</code> and
 708       <code>Server_Strategy_Factory</code> using
 709       <code>TAO::ORB::default_svc_conf_entries()</code> in a
 710       program and you also have a file called <code>svc.conf</code>
 711       which has an entry for <code>Resource_Factory</code>.  This
 712       program will use the entry for <code>Resource_Factory</code> in
 713       the <code>svc.conf</code> file, the entry for
 714       <code>Server_Strategy_Factory</code> set in the program, and the
 715       in-stock <code>Client_Strategy_Factory</code> that TAO defines. <P>
 716
 717   <li><p>Some platforms do not support reading of <code>svc.conf</code>
 718       files or perhaps you would rather not to use this feature.  In these cases,
 719       you can define <code>TAO_PLATFORM_SVC_CONF_FILE_NOTSUP</code>
 720       in your ACE <code>config.h</code> file and recompile the TAO
 721       libraries.  When this flag is set, TAO programs will not try to search for
 722       the default <code>svc.conf</code> file.  You can still use
 723       <code>-ORBSvcConf</code> to initialize the components (assuming
 724       the platform supports it).</p>
 725
 726       <p>On these platform, you can alter the default settings for
 727       TAO components by defining the following macros in your
 728       <code>config.h</code> file:</p>
 729
 730       <ul>
 731         <li><code>TAO_DEFAULT_RESOURCE_FACTORY_ARGS</code>
 732         <li><code>TAO_ADVANCED_RESOURCE_FACTORY_ARGS</code>
 733         <li><code>TAO_DEFAULT_SERVER_STRATEGY_FACTORY_ARGS</code>
 734         <li><code>TAO_DEFAULT_CLIENT_STRATEGY_FACTORY_ARGS</code>
 735       </ul>
 736
 737       <p>The ACE Makefiles <code>fakesvcconf</code> flag can be
 738       used to define <code>TAO_PLATFORM_SVC_CONF_FILE_NOTSUP</code>.
 739       To define that macro, just add <code>fakesvcconf=1</code> to
 740       your <code>make</code> invocation.
 741
 742       <p>See <a href="../tao/orbconf.h"><code>orbconf.h</code></a> for
 743       an example.
 744 </ul>
 745
 746 <hr>
 747 <h3>
 748 Configuration for Homogenous Systems<a NAME="homogenous"></a></h3>
 749
 750 <ul>
 751   <LI><b>Compile-time options</b><a NAME="homogenous_compile"></a>
 752       <p>Many real-time applications run on homogenous environments, TAO (and
 753       ACE) can take advantage of this fact by simplifying the server side demarshaling;
 754       to enable this feature you have to edit the <tt>$ACE_ROOT/ace/OS.h</tt>
 755       file and enable the macro <tt>ACE_DISABLE_SWAP_ON_READ</tt>.
 756       <p>In this systems it is also common that server and the client startup
 757       and shutdown simultaneously, in those circumstances there is no need to
 758       check the timestamps in the POA, another macro (<tt>POA_NO_TIMESTAMP</tt>)
 759       can be used for this purpose.
 760       <p>Users running in embedded systems may also need to modify the default
 761       options for TAO, the macros <tt>TAO_DEFAULT_RESOURCE_FACTORY_ARGS</tt>, <tt>TAO_ADVANCED_RESOURCE_FACTORY_ARGS</tt>,
 762       <tt>TAO_DEFAULT_CLIENT_STRATEGY_FACTORY_ARGS</tt> and <tt>TAO_DEFAULT_SERVER_STRATEGY_FACTORY_ARGS</tt>
 763       can be used for those purposes. If the footprint size is an issue users
 764       may consider writing custom strategy factories that only create the right
 765       strategies, this eliminates the parsing code for the different options.
 766
 767       <p>
 768   <LI><b>Run-time options</b><a NAME="homogenous_runtime"></a>
 769       <P>Unix systems that support local IPC (formerly known as Unix domain
 770       sockets) can take advantage of TAO's UIOP pluggable transport protocol
 771       to improve performance considerably.  To use TAO's UIOP pluggable
 772       protocol, simply specify a UIOP endpoint on the command line using
 773       the <tt>-ORBEndpoint</tt> option described in the
 774       <A HREF="Options.html">options</A> documentation.  Additional
 775       information about
 776       TAO's UIOP pluggable protocol can be found in the
 777       <A HREF="releasenotes/index.html#pp">release notes</A>.
 778       <p>
 779       <p>Some embedded systems run without the benefit of a DNS server, in that
 780       case they can use the <tt>-ORBDottedDecimalAddresses</tt> option; the ORB
 781       will avoid the use of hostnames in the profiles it generates, thus clients
 782       don't need to do any name resolution. Use the compile-time define
 783       <tt>TAO_USES_DOTTED_DECIMAL_ADDRESSES</tt> in
 784       <tt>$TAO_ROOT/tao/orbconf.h</tt> to make this the default behavior.
 785 </ul>
 786
 787 <hr>
 788 <h3>Configuration Suggestions<A name="suggestions"</A></h3>
 789
 790 Choosing the right configuration is hard and, of course, depends on your
 791 application. In the following section we will attempt to describe some
 792 motivations for features in TAO, hopefully that can guide you through the
 793 choice of your configuration options.
 794 <ul>
 795
 796   <LI><b>ORB-per-thread</b> -- The main motivation behind this options is to
 797       minimize priority inversion, since threads share no ORB resources no locking
 798       is required and thus, priority is preserved in most cases (assuming proper
 799       support from the OS). If you are not too concerned about priority inversion
 800       try to use a single ORB, using ORB-per-thread has some tradeoffs (like
 801       calling ORB_init on each thread, activation of a servant is more complicated,
 802       etc.) Some of the problems, can be minimized, but they require even more
 803       careful analysis.
 804       <p>As the reader will note this is a delicate configuration option, the
 805       rule of thumb should be <b>not</b> to use ORB-per-thread unless it is really
 806       required. <P>
 807
 808   <li>
 809
 810       <b>Collocation tables</b> -- Why would an application not want to
 811       use the global collocation table?  Because a collocated method
 812       invocation is run in the client's thread-of-control.  If objects
 813       are to serve requests only at a well
 814       known priority the application can be configured with the
 815       ORB-per-thread option, and the object is activated only in the thread
 816       (ORB) corresponding to the desired priority.  But using a global table
 817       would subvert the priority assignment (because calls would run
 818       at the priority of the client).</li><P>
 819
 820   <li> <b>Single-threaded vs. Multi-threaded Connection Handlers</b>
 821       -- The
 822       <tt>Client_Connection_Handler</tt> is the component in TAO that writes
 823       the requests to the underlying transport socket; this is also the
 824       component that reads the response back from the server.</li>
 825
 826       <p>
 827
 828       While waiting for this response new requests to the local ORB can
 829       arrive, this is the so-called nested upcall support. TAO supports two
 830       mechanisms for handling nested upcalls, the default uses the
 831       leader-follower model to allow multiple threads to wait on a single
 832       reactor for several concurrent requests; sometimes this configuration
 833       can be an overkill, if only one thread is using a reactor at the same
 834       time a lighter weight implementation can be used.  <p>This
 835       configuration is controlled by the <tt>-ORBClientConnectionHandler</tt>
 836       option, good opportunities to use this option are:<P>
 837
 838       <ul>
 839         <li> Single threaded servers</li>
 840
 841         <li> Servers running in ORB-per-thread mode (pseudo single
 842             threaded.)</li>
 843
 844         <li> Pure clients that will never receive a request</li>
 845       </ul><P>
 846
 847 <li>
 848     <b>Allocator for input CDR streams</b> -- Normally the application has no
 849     access to this buffer, and it is only used on the demarshaling of arguments
 850     (or results). It is almost always better to use the "<tt>-ORBInputCDRAllocator
 851     null</tt>" option since it will allocate memory from a thread specific allocator
 852     and it will not need locks to manage that memory.</li>
 853
 854     <p>In some cases the user <i>may</i> gain access to the CDR stream
 855     buffer: TAO makes no copies when demarshaling octet sequences, instead
 856     the octet sequence simply points to the CDR buffer, since the octet
 857     sequence does not own this buffer a copy must be made if the user
 858     wants to keep the buffer after the upcall.
 859
 860     <p>The user can, however, increase the reference count on the CDR
 861     stream buffer, thus allowing her to extend the lifetime of this
 862     buffer. Still passing this buffer to another thread and attempting to
 863     release it in that thread will result in some memory leak or
 864     corruption. Users willing to use this feature of TAO can still do so,
 865     <b>if</b> they use a global allocator for their input CDR stream, but
 866     that will introduce extra locking on the critical path.  <p>As the
 867     reader can see this is an option that has limited applicability and
 868     requires careful consideration of the tradeoffs involved.
 869 </ul>
 870
 871 <hr>
 872 <p>Back to the TAO <a href="components.html">component options and tuning documentation</a>.<!--#include virtual="/~schmidt/cgi-sig.html" -->
 873 </body>
 874 </html>