TAO/docs/ec_options.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>Real-Time Event Channel Configuration</title>
   5     <!-- -->
   6   </head>
   7
   8   <body>
   9     <CENTER>
  10     <h1>Real-Time Event Channel Configuration</h1>
  11     </CENTER>
  12
  13     <H3>Configuring the Event Channel at Compilation Time</H3>
  14
  15     <P>TAO's Real-Time Event Channel can be configured at compilation
  16       time to use a different payload than its default.  To do so
  17       there are several options:
  18     </P>
  19
  20     <UL>
  21       <LI><P>To eliminate the <CODE>CORBA::Any</CODE> field in the
  22           event payload you should define the
  23           <CODE>TAO_LACKS_EVENT_CHANNEL_ANY</CODE>
  24           macro when invoking the IDL compiler.
  25           You can do as follows:
  26 <PRE>
  27 $ cd $TAO_ROOT/orbsvcs/orbsvcs
  28 $ make TAO_IDLFLAGS=-DTAO_LACKS_EVENT_CHANNEL_ANY
  29 </PRE>
  30         </P>
  31       </LI>
  32       <LI><P>Similarly you can eliminate the octet sequence field in
  33           the event payload using:
  34 <PRE>
  35 $ cd $TAO_ROOT/orbsvcs/orbsvcs
  36 $ make TAO_IDLFLAGS=-DTAO_LACKS_EVENT_CHANNEL_OCTET_SEQUENCE
  37 </PRE>
  38         </P>
  39       </LI>
  40       <LI><P>Finally you can provide your own event payload, to do
  41           this you should Replace the contents of the
  42           <CODE>RtecDefaultEventData.idl</CODE>
  43           and define some IDL structure named
  44           <CODE>RtecEventData</CODE>.
  45           For example, you could define you own event type as follows:
  46 <PRE>
  47 // Replace RtecDefaultEventData.idl with this:
  48
  49 struct RtecEventData
  50 {
  51   sequence&lt;long&gt; my_event_payload;
  52 };
  53 </PRE>
  54       </LI>
  55     </UL>
  56
  57     <H3>Run-time Configuration</H3>
  58
  59     <P>The new implementation of the real-time event channel uses a
  60       factory to build all the objects and strategies it requires.
  61       The factory can be dynamically loaded using ACE Service
  62       Configurator, this is extremely convenient because the factory
  63       can also parse options in the Service Configurator script file.
  64     </P>
  65
  66     <P>There are currently several implementations of the factory.
  67       <ul>
  68 <li>The <em>default</em> factory supports all of
  69       the options below and most of the potential values, except as
  70       specifically indicated.
  71 <li>
  72       The <em>sched</em> factory defines new option values as indicated
  73       below that allow the RTES to integrate with the Real-Time
  74       Scheduling Service.  Use of the <em>sched</em> factory requires
  75       that you link in the TAO_RTSchedEvent library.
  76 <li>
  77         The <em>tpc</em> (thread per consumer) factory defines new
  78         options values as indicated below.  This
  79           strategy is similar to the MT dispatching strategy in that it
  80           separates the thread that receives the push() from a supplier
  81           from the thread that does the eventual push() to the
  82           consumer(s), but it differs from MT in that MT has a pool of
  83           threads pulling from a single queue and ultimately potentially
  84           servicing every consumer, whereas TPC has a queue for <em>each</em>
  85           consumer and, thus, a single thread dedicated to pushing to that
  86           consumer.  This insures that a badly-behaved consumer <b>CANNOT</b>
  87           have an adverse effect on the channel or supplier.<br>
  88         To use this new strategy you will have to replace the call in your code
  89           for <code>TAO_EC_Default_Factory::init_svcs()</code> with
  90           <code>TAO_EC_TPC_Factory::init_svcs()</code>.
  91
  92 <li>      The <em>basic</em> and <em>null</em> factories are hard-coded
  93       factories that do not support any configuration options.
  94       They both define simple configurations that may enable some
  95       applications to use the RTES in a smaller footprint.
  96       See the files
  97       <code>$TAO_ROOT/orbsvcs/orbsvcs/Event/EC_Null_Factory.h</code>
  98       and <code>$TAO_ROOT/orbsvcs/orbsvcs/Event/EC_Basic_Factory.h</code>
  99       for details.
 100     </ul>
 101     </P>
 102
 103 <h3>Special Topic: Queue Configuration</h3>
 104     <p>
 105       In certain configurations such as <em>mt</em> and <em>tpc</em>,
 106       the RTES implementation uses something called
 107       <code>TAO_EC_Queue</code>, which is an in-memory queue that
 108       separates threads that receive <code>push()</code> invocations
 109       from suppliers from the threads that dispatch
 110       <code>push()</code> invocations to consumers.  A user of the
 111       RTES can configure some behaviors of this queue as well as
 112       behaviors when the queue reaches certain trigger points.  The
 113       configuration of these behaviors is a combination of
 114       compile-time and run-time specification.
 115     </p>
 116     <p>
 117       The queue itself has two trigger points for the number of
 118       invocations in the queue:
 119       <ul>
 120       <li><em>low-water mark (LWM)</em>, a lower threshold below which the
 121       queue allows more invocations to be placed into the queue;
 122       <li><em>high-water mark (HWM)</em>, an upper threshold above which the
 123       queue prevents more invocations from being added to the queue
 124       </ul>
 125     The values for these can be set at compile time via
 126     <code>TAO_EC_QUEUE_LWM</code> and <code>TAO_EC_QUEUE_HWM</code>
 127     for the low-water mark and high-water mark, respectively.
 128     <p>
 129       In addition, an application can specify what the RTES should do if a
 130       queue reaches the HWM, i.e., fills up.  This behavior is encapsulated in a
 131       derivation of an <code>ACE_Service_Object</code>, called
 132       <code>TAO_EC_Queue_Full_Service_Object</code>.  The RTES looks
 133       for a service object of a particular name (the default for this
 134       name is in macro TAO_EC_DEFAULT_QUEUE_FULL_SERVICE_OBJECT_NAME,
 135       which is "EC_QueueFullSimpleActions") and invokes
 136       <code>queue_full_action()</code> on the instance.  See class
 137       <code>TAO_EC_Simple_Queue_Full_Action</code> in file
 138       <code>$TAO_ROOT/orbsvcs/orbsvcs/Event/EC_Dispatching_Task.h</code>
 139       for an example.  This particular example can be configured to
 140       either <em>wait</em> or <em>discard</em> new invocations on
 141       reaching the HWM.
 142     </p>
 143
 144     <H3>The configuration file</H3>
 145
 146     <P>The real-time event channel uses the same service configurator
 147       file that the ORB uses, the default name for this file is
 148       <CODE>svc.conf</CODE>, but the ORB option
 149       <CODE>-ORBSvcConf</CODE> can be used to override this.
 150       The format of the file is described in detail in
 151       the service configurator documentation, but the relevant section
 152       for the event channel looks like this:
 153     </P>
 154
 155 <PRE>
 156 # Comments go here...
 157 # More comments if you want to...
 158 static EC_Factory "-ECFiltering basic ....."
 159 # ...and optionally...
 160 static EC_QueueFullSimpleActions "[wait | discard]"
 161 # ...or you can define your own TAO_EC_Queue_Full_Service_Object,
 162 #    give it whatever name you want and use -ECQueueFullServiceObject
 163 #    (see below) to specify that object's service configurator tag.
 164 </PRE>
 165
 166     <p>
 167     The
 168       table below describes all of the options (and values) supported by
 169       these factories.
 170     <P>All the event service factory options start with
 171       <CODE>-EC</CODE></P>
 172
 173
 174     <H3>The options</H3>
 175
 176     <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
 177         <TR>
 178           <TH>Option</TH>
 179           <TH>Description</TH>
 180         </TR>
 181
 182         <!-- <TR NAME="ECDispatching"> -->
 183         <TR>
 184           <TD><CODE>-ECDispatching</CODE>
 185             <EM>dispatching_strategy</EM>
 186           </TD>
 187           <TD>Select the dispatching strategy used by the real-time
 188             event service. The <EM>reactive</EM> strategy uses the
 189             same thread that received the event from the supplier to
 190             push the event to all the consumers.<br>
 191             The <EM>priority</EM> strategy (sched factory only) uses
 192             a prioritized pool
 193             of threads and queries the scheduling service to select
 194             the thread that dispatches each event.<br>
 195             The <EM>mt</EM> strategy also uses a pool of threads,
 196             but the thread to dispatch is randomly selected.<br>
 197             <b>Does not apply to the <em>tpc</em> factory.</b>
 198           </TD>
 199         </TR>
 200
 201         <!-- <TR NAME="ECDispatchingThreads"> -->
 202         <TR>
 203           <TD><CODE>-ECDispatchingThreads</CODE>
 204             <EM>number_of_threads</EM>
 205           </TD>
 206           <TD>Select the number of threads used by the <EM>mt</EM>
 207             dispatching strategy.<br>
 208             <b>Does not apply to the <em>tpc</em> factory.</b>
 209           </TD>
 210         </TR>
 211         <!-- <TR NAME="ECDispatchingThreadFlags"> -->
 212         <TR>
 213           <td><code>-ECDispatchingThreadFlags</code>
 214             <em>thread_flags</em><b>:</b><em>thread_priority</em>
 215             </td>
 216           <td>
 217             Provide flags and priority used for creation of
 218             dispatching threads.<br>
 219             <em>thread_flags</em> is a set of
 220             <code>THR_</code> flags separated by the vertical bar
 221             ('|'), e.g.,
 222             <code>THR_BOUND|THR_NEW_LWP|THR_SCOPE_SYSTEM</code>.
 223             <br>
 224             <em>thread_priority</em> is a numeric value indicating the
 225             desired priority at which the thread should be created.
 226             No range checking is performed on the value prior to
 227             passing to the thread creation function.  Also note that
 228             priorities are platform-specific, so a valid value for a
 229             given set of flags on one platform may not work with the
 230             same flags on another platform.
 231           </tr>
 232
 233         <!-- <TR  NAME="ECQueueFullServiceObject"> -->
 234         <tr>
 235           <td><code>-ECQueueFullServiceObject</code>
 236             <em>service_object_name</em>
 237             </td>
 238           <td>
 239             Used to specify the name/tag in the service configurator
 240             through which the RTEC should look for a "queue full
 241             service object".<br>
 242             <b>Will only have an effect on dispatch strategies that
 243             use <code>TAO_EC_Queue</code>.</b>
 244           </td>
 245         </tr>
 246         <!-- <TR NAME="ECFiltering"> -->
 247         <TR>
 248           <TD><CODE>-ECFiltering</CODE>
 249             <EM>consumer_filtering_strategy</EM>
 250           </TD>
 251           <TD>Select the filtering strategy used by the consumers.
 252             The <EM>null</EM> filtering strategy will build trivial
 253             filters for all consumers.
 254             The <EM>basic</EM> filtering strategy supports
 255             disjunction, conjunction, logical and, negation, bitmask,
 256             and timeout filters based on the subscriptions passed by
 257             the consumer during the connect call. It only supports limited
 258             nesting of filter groups.
 259             The <EM>prefix</EM> filtering strategy supports
 260             all filter types that the <EM>basic</EM> strategy does
 261             and allows unlimited nesting of filter groups.
 262             When using the <EM>prefix</EM> strategy, the source field of the
 263             group filter must specify the number of children in the group.
 264             The <EM>priority</EM> filtering strategy  (sched factory only)
 265             supports the same
 266             features as the <EM>basic</EM> filtering strategy, but it
 267             also collaborates with the scheduling service to build the
 268             dependency graph.
 269           </TD>
 270         </TR>
 271
 272         <!-- <TR NAME="ECSupplierFiltering"> -->
 273         <TR>
 274           <TD><CODE>-ECSupplierFiltering</CODE>
 275             <EM>supplier_filtering_strategy</EM>
 276           </TD>
 277           <TD>The event channel can also perform some filtering close
 278             to the suppliers by minimizing the number of consumers
 279             that are tested for given event.
 280             If the strategy is <EM>null</EM> then a global collection
 281             of consumers is maintained and each event is filtered by
 282             each consumer.
 283             If the strategy is <EM>per-supplier</EM> then the EC uses
 284             the supplier publications and the consumer subscriptions
 285             to determine which consumers could potentially be
 286             interested in events for each supplier.
 287             This set of consumers is usually smaller than the complete
 288             set and it is thus faster to traverse it, but keeping more
 289             collections of consumers increases the connection and
 290             disconnection time as well as the memory requirements.
 291           </TD>
 292         </TR>
 293
 294         <!-- <TR NAME="ECTimeout"> -->
 295         <TR>
 296           <TD><CODE>-ECTimeout</CODE>
 297             <EM>timeout_strategy</EM>
 298           </TD>
 299           <TD>A consumer can request that the event channel generate
 300             periodic or oneshot timeout events.
 301             This option controls the strategy to generate the
 302             timeouts,
 303             using <EM>reactive</EM> the same reactor used for the ORB
 304             is used by the event service.
 305             The <EM>priority</EM> strategy  (sched factory only) uses a
 306             prioritized group of
 307             threads, timeouts with higher rate are generated by
 308             threads of higher priority.
 309             <BR><B>NOTE: The <EM>priority</EM> strategy is not
 310               implemented</B>
 311           </TD>
 312         </TR>
 313
 314         <!-- <TR NAME="ECObserver"> -->
 315         <TR>
 316           <TD><CODE>-ECObserver</CODE>
 317             <EM>observer</EM>
 318           </TD>
 319           <TD>The event channel uses the Observer pattern to report
 320             changes in the subscriptions and publications of its
 321             suppliers and consumers; this is especially useful in the
 322             implementation of event channel gateways.
 323             The user can disable this feature by selecting the
 324             <EM>null</EM> strategy;
 325             whereas the <EM>basic</EM> strategy provides a simple, yet
 326             efficient implementation. <EM>reactive</EM> provides a
 327             strategy in which an observer that is unreachable is removed
 328             from the observer list.
 329             <BR><B>NOTE:<B> The default is to have the feature disabled.
 330           </TD>
 331         </TR>
 332
 333         <!-- <TR NAME="ECScheduling"> -->
 334         <TR>
 335           <TD><CODE>-ECScheduling</CODE>
 336             <EM>scheduling_strategy</EM>
 337           </TD>
 338           <TD>The event channel can collaborate with the scheduling
 339             service to build the dependency list between the consumers
 340             and the suppliers.
 341             If the <EM>null</EM> scheduling strategy is selected this
 342             feature is disabled,
 343             the <EM>priority</EM> strategy (sched factory only) enables this feature.
 344             <BR><B>NOTE:<B> The default is to have the feature disabled.
 345           </TD>
 346         </TR>
 347
 348         <!-- <TR NAME="ECProxyConsumerLock"> -->
 349         <TR>
 350           <TD><CODE>-ECProxyConsumerLock</CODE>
 351             <EM>lock_type</EM>
 352           </TD>
 353           <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or
 354             <EM>recursive</EM>) to synchronize access to the
 355             ProxyPushConsumer state.
 356           </TD>
 357         </TR>
 358
 359         <!-- <TR NAME="ECProxySupplierLock"> -->
 360         <TR>
 361           <TD><CODE>-ECProxySupplierLock</CODE>
 362             <EM>lock_type</EM>
 363           </TD>
 364           <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or
 365             <EM>recursive</EM>) to synchronize access to the
 366             ProxyPushSupplier state.
 367           </TD>
 368         </TR>
 369
 370         <!-- <TR NAME="ECUseORBId"> -->
 371         <TR>
 372           <TD><CODE>-ECUseORBId</CODE>
 373             <EM>orbid</EM>
 374           </TD>
 375           <TD>Set the name of the ORB used by the event service, only
 376             useful in applications that create multiple ORBs and
 377             activate the event service in one of them.
 378           </TD>
 379         </TR>
 380
 381         <!-- <TR NAME="ECConsumerControl"> -->
 382         <TR>
 383           <TD><CODE>-ECConsumerControl</CODE>
 384             <EM>policy</EM>
 385           </TD>
 386           <TD>Select the consumer control policy (<EM>null</EM> or
 387             <EM>reactive</EM>) to detect and discard broken consumers.
 388           </TD>
 389         </TR>
 390
 391         <!-- <TR NAME="ECSupplierControl"> -->
 392         <TR>
 393           <TD><CODE>-ECSupplierControl</CODE>
 394             <EM>policy</EM>
 395           </TD>
 396           <TD>Select the supplier control policy (<EM>null</EM> or
 397             <EM>reactive</EM>) to detect and discard broken suppliers.
 398           </TD>
 399         </TR>
 400
 401         <!-- <TR NAME="ECConsumerControlPeriod"> -->
 402         <TR>
 403           <TD><CODE>-ECConsumerControlPeriod</CODE>
 404             <EM>period</EM>
 405           </TD>
 406           <TD>Set the period (in microseconds) used by the reactive
 407             consumer control policy (set <EM>ECConsumerControl</EM> to
 408             <EM>reactive</EM>) to poll the state of the consumers.
 409             When set to 0 there is no polling but the
 410             reactive strategy is in place.
 411           </TD>
 412         </TR>
 413
 414         <!-- <TR NAME="ECSupplierControlPeriod"> -->
 415         <TR>
 416           <TD><CODE>-ECSupplierControlPeriod</CODE>
 417             <EM>period</EM>
 418           </TD>
 419           <TD>Set the period (in microseconds) used by the reactive
 420             supplier control policy (set <EM>ECSupplierControl</EM> to
 421             <EM>reactive</EM>) to poll the state of the suppliers.
 422             When set to 0 there is no polling but the
 423             reactive strategy is in place.
 424           </TD>
 425         </TR>
 426
 427         <!-- <TR NAME="ECConsumerControlTimeout"> -->
 428         <TR>
 429           <TD><CODE>-ECConsumerControlTimeout</CODE>
 430             <EM>timeout</EM>
 431           </TD>
 432           <TD>Set the timeout period (in microseconds) used by the reactive
 433             consumer control policy (set <EM>ECConsumerControl</EM> to
 434             <EM>reactive</EM>) to detect a timeout when polling the state
 435             of the consumers.
 436           </TD>
 437         </TR>
 438
 439         <!-- <TR NAME="ECSupplierControlTimeout"> -->
 440         <TR>
 441           <TD><CODE>-ECSupplierControlTimeout</CODE>
 442             <EM>timeout</EM>
 443           </TD>
 444           <TD>Set the timeout period (in microseconds) used by the reactive
 445             supplier control policy (set <EM>ECSupplierControl</EM> to
 446             <EM>reactive</EM>) to detect a timeout when polling the state
 447             of the suppliers.
 448           </TD>
 449         </TR>
 450
 451         <!-- <TR NAME="ECProxyPushConsumerCollection"> -->
 452         <TR>
 453           <TD><CODE>-ECProxyPushConsumerCollection</CODE>
 454             <EM>flag[:flags]</EM>
 455           </TD>
 456           <TD><P>Configure the data structure and strategies used to
 457               implement collections of
 458               <CODE>ProxyPushConsumers</CODE>.
 459               The argument is a colon separated list of flags, with
 460               the following semantics:
 461               <TABLE BORDER="1" CELLSPACING="2" CELLPADDING="0">
 462               <TR><TH>Flag</TH><TH>Description</TH>
 463               </TR>
 464               <TR>
 465                 <TD>MT</TD>
 466                 <TD>Use regular mutexes and/or condition
 467                   variables for serialization.
 468                 </TD>
 469                 </tr>
 470               <TR>
 471                 <TD>ST</TD>
 472                 <TD>Use null mutexes and/or condition
 473                   variables for serialization.
 474                 </TD>
 475                 </tr>
 476               <TR>
 477                 <TD>LIST</TD>
 478                 <TD>Implement the collection using an ordered list,
 479                   fast for iteration (i.e. during event dispatching),
 480                   but slow for insertion and removal (i.e. when
 481                   clients connect and disconnect from the EC).
 482                 </TD>
 483                 </tr>
 484               <TR>
 485                 <TD>RB_TREE</TD>
 486                 <TD>Implement the collection using a Red-Black tree,
 487                   slow for iteration (i.e. during event dispatching),
 488                   but fast for insertion and removal (i.e. when
 489                   clients connect and disconnect from the EC).
 490                 </TD>
 491                 </tr>
 492               <TR>
 493                 <TD>IMMEDIATE</TD>
 494                 <TD>Threads block until they can execute a change on
 495                   the data structure, the system must use other
 496                   approaches to guarantee that the iterators are not
 497                   invalidated during event dispatching.  For example,
 498                   use a separate dispatching thread.  Using this option
 499                   with the reactive values for any of the
 500                   -ECSupplierControl, -ECConsumerControl, or
 501                   -ECDispatching options may cause deadlocks.
 502                 </TD>
 503                 </tr>
 504               <TR>
 505                 <TD>COPY_ON_READ</TD>
 506                 <TD>Before initiating an iteration to dispatch events
 507                   (or similar tasks) a copy of the complete collection
 508                   is performed.
 509                   This solves most of the synchronization problems,
 510                   but introduces a significant source of overhead and
 511                   priority inversions on the critical path.
 512                 </TD>
 513                 </tr>
 514               <TR>
 515                 <TD>COPY_ON_WRITE</TD>
 516                 <TD>Similar to the previous one, but the copy is only
 517                   performed when needed.
 518                 </TD>
 519                 </tr>
 520               <TR>
 521                 <TD>DELAYED</TD>
 522                 <TD>Threads that need to change the collection can
 523                   detect if that change will invalidate iterators used
 524                   by other threads.
 525                   If so, the thread posts the change on a queue that
 526                   is executed once the collection is no longer in
 527                   use.
 528                 </TD>
 529               </TR>
 530               </TABLE>
 531             </P>
 532           </TD>
 533         </TR>
 534
 535         <!-- <TR NAME="ECProxyPushSupplierCollection"> -->
 536         <TR>
 537           <TD><CODE>-ECProxyPushSupplierCollection</CODE>
 538             <EM>flag[:flags]</EM>
 539           </TD>
 540           <TD><P>Configure the data structure and strategies used to
 541               implement collections of <CODE>ProxyPushSupplier</CODE>
 542               objects.
 543               Use the same arguments as with the
 544               <CODE>ECProxyPushConsumerCollection</CODE> option.
 545             </P>
 546           </TD>
 547         </TR>
 548
 549         <!-- <TR NAME="ECConsumerValidateConnection"> -->
 550         <TR>
 551           <TD><CODE>-ECConsumerValidateConnection</CODE>
 552             <EM>validate_connection: 0 | 1</EM>
 553           </TD>
 554           <TD>When this option is set the connection from the Event Channel
 555             to the consumer will be created during the connect of the
 556             consumer, just before the consumer is added to the consumer
 557             list. By default
 558             the Event Channel will create the connection to the consumer at
 559             the moment the first event is pushed to the consumer.
 560             When the network is heavily loaded during this connect and a new event
 561             is pushed before the connection is established, a new create connection
 562             request is done. When having very high connection establishment
 563             time (for example running on a WAN) and an interval that is much
 564             smaller than the connection establishment time it is wise to
 565             set this option. Else you get dozens of new connection request
 566             that can result in a stack overflow. Another option is to use BiDIR
 567             GIOP so that there is only one connection between Rtec and consumer
 568             but for this the Rtec and the consumer must be changed to set the
 569             BiDIR Policy, this is not implemented at this moment.
 570           </TD>
 571         </TR>
 572
 573       </TABLE>
 574     </P>
 575
 576     <H3>The constructor</H3>
 577
 578     <P>The <CODE>TAO_EC_Event_Channel</CODE> class implements the
 579       <CODE>RtecEventChannelAdmin::EventChannel</CODE> interface;
 580       this class takes one mandatory and two optional parameters in
 581       its constructor:
 582     </P>
 583
 584 <PRE>
 585   TAO_EC_Event_Channel (const TAO_EC_Event_Channel_Attributes& attributes,
 586                         TAO_EC_Factory* factory = 0,
 587                         int own_factory = 0);
 588 </PRE>
 589
 590     <P>The <CODE>factory</CODE> is an optional parameter to override
 591       the default strategy factory used by the event channel,
 592       the event channel will destroy the factory if the
 593       <CODE>own_factory</CODE> argument is true.
 594     </P>
 595
 596     <P>The <CODE>attributes</CODE> parameter can be used to fine tune
 597       some of the algorithms and strategies used by the event channel,
 598       the default values are probably OK for most applications.
 599       Notice that the attributes include the POA used to activate the
 600       ConsumerAdmin, SupplierAdmin, ProxyPushConsumer and
 601       ProxyPushSupplier objects;
 602       these POAs must have the <CODE>IMPLICIT_ACTIVATION</CODE> and the
 603       <CODE>SYSTEM_ID</CODE> policies (as the RootPOA does).
 604     </P>
 605
 606     <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
 607         <TR><TH>Attribute</TH><TH>Description</TH></TR>
 608
 609         <TR><TD><CODE>consumer_reconnect</CODE></TD>
 610           <TD>If the attribute is not zero then the same consumer can
 611             call <CODE>connect_push_consumer</CODE> on its
 612             ProxyPushSupplier multiple times to change its
 613             subscriptions;
 614             this is usually more efficient that disconnecting and
 615             connecting again.
 616           </TD>
 617         </TR>
 618
 619         <TR><TD><CODE>supplier_reconnect</CODE></TD>
 620           <TD>If the attribute is not zero then the same supplier can
 621             call <CODE>connect_push_supplier</CODE> on its
 622             ProxyPushConsumer multiple times to change its
 623             publications;
 624             this is usually more efficient that disconnecting and
 625             connecting again.
 626           </TD>
 627         </TR>
 628
 629         <TR><TD><CODE>busy_hwm</CODE></TD>
 630           <TD>When the delayed flag is set on proxy collections,
 631             this flag controls the maximum
 632             number of threads that can simultaneously iterate over the
 633             collection before blocking.
 634             It can be used to avoid starvation in delayed updates on
 635             the collection.
 636           </TD>
 637         </TR>
 638
 639         <TR><TD><CODE>max_write_delay</CODE></TD>
 640           <TD>When the delayed flag is set on proxy collections,
 641             this flag controls the maximum
 642             number of threads that will initiate dispatching
 643             <B>after</B> a change has been posted.
 644             Any thread after that is blocked until the operations are
 645             performed.
 646             It can be used to completely stop starvation of delayed
 647             updates on the collection.
 648           </TD>
 649         </TR>
 650
 651         <TR><TD><CODE>scheduler</CODE></TD>
 652           <TD>Most configurations of the real-time event channel do
 653             not require an scheduler.
 654             If any of the strategies that require an scheduling
 655             service is selected then this attribute should be set
 656             appropriately.
 657           </TD>
 658         </TR>
 659
 660         <TR><TD><CODE>supplier_poa</CODE></TD>
 661           <TD>The POA used by the event channel to activate SupplierAdmin
 662             and SupplierProxy objects.
 663           </TD>
 664         </TR>
 665
 666         <TR><TD><CODE>consumer_poa</CODE></TD>
 667           <TD>The POA used by the event channel to activate ConsumerAdmin
 668             and ConsumerProxy objects.
 669           </TD>
 670         </TR>
 671
 672         <TR><TD><CODE>disconnect_callbacks</CODE></TD>
 673           <TD>If not zero, then the event channel sends disconnect
 674             callbacks when a disconnect method is called on a Proxy.
 675             For example, if a consumer calls
 676             disconnect_push_supplier() on its proxy the EC
 677             invokes disconnect_push_consumer() on the consumer.
 678             An analogous call is also made for suppliers when this
 679             attribute is set.
 680             By default, these callbacks are not made in this situation.
 681           </TD>
 682         </TR>
 683       </TABLE>
 684     </P>
 685
 686     <H3>Configuring the IIOP Gateway</H3>
 687
 688     <P>The <CODE>TAO_EC_Gateway_IIOP_Factory</CODE> is the factory for
 689       the <CODE>TAO_EC_Gateway_IIOP</CODE> class. This factory can be
 690       used to configure the settings of the IIOP Gateway using the
 691       svc.conf file. The contents looks like this:
 692     </P>
 693
 694 <PRE>
 695 # Comments go here...
 696 # More comments if you want to...
 697 static EC_Gateway_IIOP_Factory "-ECGIIOPConsumerECControl null ....."
 698 </PRE>
 699
 700     <P>All the IIOP Gateway factory options start with
 701       <CODE>-ECGIIOP</CODE></P>
 702
 703     <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
 704         <TR>
 705           <TH>Option</TH>
 706           <TH>Description</TH>
 707         </TR>
 708
 709         <!-- <TR NAME="ECGIIOPConsumerECControl"> -->
 710         <TR>
 711           <TD><CODE>-ECGIIOPConsumerECControl</CODE>
 712             <EM>policy</EM>
 713           </TD>
 714           <TD>Select the consumer ec control policy (<EM>null</EM> or
 715             <EM>reactive</EM> or <EM>reconnect</EM>) to detect and handle
 716              broken consumer ec's.
 717           </TD>
 718         </TR>
 719         <!-- <TR NAME="ECGIIOPConsumerECControlPeriod"> -->
 720         <TR>
 721           <TD><CODE>-ECGIIOPConsumerECControlPeriod</CODE>
 722             <EM>period</EM>
 723           </TD>
 724           <TD>Set the period (in microseconds) used by the reactive and reconnect
 725             consumer ec control policy (set <EM>ECGIIOPConsumerECControl</EM> to
 726             <EM>reactive</EM> or <EM>reconnect</EM>) to poll the state of the consumer ec.
 727             When set to 0 there is no polling but the
 728             reactive strategy is in place.
 729           </TD>
 730         </TR>
 731
 732         <!-- <TR NAME="ECGIIOPConsumerECControlTimeout"> -->
 733         <TR>
 734           <TD><CODE>-ECGIIOPConsumerECControlTimeout</CODE>
 735             <EM>timeout</EM>
 736           </TD>
 737           <TD>Set the timeout period (in microseconds) used by the reactive and reconnect
 738             consumer ec control policy (set <EM>ECGIIOPConsumerECControl</EM> to
 739             <EM>reactive</EM> or <EM>reconnect</EM>) to detect a timeout when polling the state
 740             of the consumer ec.
 741           </TD>
 742         </TR>
 743
 744         <!-- <TR NAME="ECGIIOPUseORBId"> -->
 745         <TR>
 746           <TD><CODE>-ECGIIOPUseORBId</CODE>
 747             <EM>orbid</EM>
 748           </TD>
 749           <TD>Set the name of the ORB used by the event gateway, only
 750             useful in applications that create multiple ORBs and
 751             activate the gateway in one of them.
 752           </TD>
 753         </TR>
 754
 755         <!-- <TR NAME="ECGIIOPUseTTL"> -->
 756         <TR>
 757           <TD><CODE>-ECGIIOPUseTTL</CODE>
 758             <EM>use_ttl: 0 | 1</EM>
 759           </TD>
 760           <TD>Set whether the IIOP Gateway uses the TTL or not.
 761             This is 1 by default. When set to 0 make sure that
 762             no recursive structure is build between ec's, else an
 763             event can keep looping for ever. Useful when there are no
 764             recursive structures and we want the gateway to
 765             transfer all events independent of their TTL because suppliers
 766             can be unaware about the maximum number of hops. In case
 767             this option is 0, the TTL in the event isn't decremented
 768             by the gateway also.
 769           </TD>
 770         </TR>
 771
 772         <!-- <TR NAME="ECGIIOPUseConsumerProxyMap"> -->
 773         <TR>
 774           <TD><CODE>-ECGIIOPUseConsumerProxyMap</CODE>
 775             <EM>use_consumer_proxy_map: 0 | 1</EM>
 776           </TD>
 777           <TD>Set whether the IIOP Gateway uses a map with a proxy
 778             push consumer for each unique source id or not. This is 1
 779             by default meaning that a map is used. When set to 0 the
 780             gateway will just use one proxy push consumer to push
 781             events to the consumer ec. This options is useful when
 782             a lot of different source id's are used but there is no
 783             need for a different proxy push consumer for each source id.
 784             Setting this option to 0 then improves the performance.
 785           </TD>
 786         </TR>
 787       </TABLE>
 788     </P>
 789
 790     <H3>The commandline arguments</H3>
 791
 792     The Event_Service executable has several commandline arguments you can use.
 793     The following arguments are available.
 794
 795     <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
 796         <TR>
 797           <TH>Option</TH>
 798           <TH>Description</TH>
 799         </TR>
 800
 801         <!-- <TR NAME="-d"> -->
 802         <TR>
 803           <TD><CODE>-n</CODE>
 804             <EM>service_name</EM>
 805           </TD>
 806           <TD>The name with which the Event Service registers itself in the
 807     Naming Service.
 808           </TD>
 809         </TR>
 810         <!-- <TR NAME="-o"> -->
 811         <TR>
 812           <TD><CODE>-o</CODE>
 813             <EM>ior_file_name</EM>
 814           </TD>
 815           <TD>The file to which the IOR of the Event Service will be written.
 816           </TD>
 817         </TR>
 818
 819         <!-- <TR NAME="-p"> -->
 820         <TR>
 821           <TD><CODE>-p</CODE>
 822             <EM>pid_file_name</EM>
 823           </TD>
 824           <TD>The process id of the Event Service will be written to this
 825           file
 826           </TD>
 827         </TR>
 828
 829         <!-- <TR NAME="-q"> -->
 830         <TR>
 831           <TD><CODE>-q</CODE>
 832             <EM>ec_object_id</EM>
 833           </TD>
 834           <TD>The object ID for the Event Channel that will be used
 835           when a Persistent IOR is generated
 836           </TD>
 837         </TR>
 838
 839         <!-- <TR NAME="-b"> -->
 840         <TR>
 841           <TD><CODE>-b</CODE>
 842             <EM></EM>
 843           </TD>
 844           <TD>Use BiDIR GIOP
 845           </TD>
 846         </TR>
 847
 848         <!-- <TR NAME="-x"> -->
 849         <TR>
 850           <TD><CODE>-x</CODE>
 851             <EM></EM>
 852           </TD>
 853           <TD>Don't register the Event Service to the Naming Service
 854           </TD>
 855         </TR>
 856
 857         <!-- <TR NAME="-s"> -->
 858         <TR>
 859           <TD><CODE>-s</CODE>
 860             <EM>global|local|none</EM>
 861           </TD>
 862           <TD>Which scheduler should be used. The default is <CODE>none</CODE>.
 863           With <CODE>local</CODE> an in process scheduler is created. With
 864           <CODE>global</CODE> a scheduler is retrieved from the Naming Service
 865           </TD>
 866         </TR>
 867       </TABLE>
 868     </P>
 869
 870     <P><HR><P>
 871
 872       Back to the TAO <A HREF="index.html">components documentation</A>.
 873
 874       <!--#include virtual="/~schmidt/cgi-sig.html" -->
 875
 876 <!--    <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address>-->
 877 <!-- Created: Thu Jul  1 21:44:28 CDT 1999 -->
 878 <!-- hhmts start -->
 879 Last modified: Tue Oct 18 13:13:54 CDT 2005
 880 <!-- hhmts end -->
 881   </body>
 882 </html>