TAO/docs/cec_options.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>COS Event Channel Configuration</title>
   5     <!--  -->
   6   </head>
   7
   8   <body>
   9     <CENTER>
  10     <h1>COS Event Channel Configuration</h1>
  11     </CENTER>
  12
  13     <H3>Run-time Configuration</H3>
  14
  15     <P>The new implementation of the COS Event Service uses a
  16       factory to build all the objects and strategies it requires.
  17       The factory can be dynamically loaded using ACE Service
  18       Configurator, this is extremely convenient because the factory
  19       can also parse options in the Service Configurator script file.
  20     </P>
  21
  22     <P>The current implementation provides a default implementation
  23       for this Factory, this document describes the options used by
  24       this default implementation.
  25       Users can define their own implementation, with new ad-hoc
  26       strategies or with pre-selected strategies.
  27     </P>
  28
  29     <H3>The configuration file</H3>
  30
  31     <P>The COS channel uses the same service configurator
  32       file that the ORB uses, the default name for this file is
  33       <CODE>svc.conf</CODE>, but the ORB option
  34       <CODE>-ORBSvcConf</CODE> can be used to override this.
  35       The format of the file is described in detail in
  36       the service configurator documentation, but the relevant section
  37       for the event channel looks like this:
  38     </P>
  39
  40 <PRE>
  41 # Comments go here...
  42 # More comments if you want to...
  43 static CEC_Factory "-CECDispatching reactive ....."
  44 </PRE>
  45
  46     <P>All the event service factory options start with
  47       <CODE>-CEC</CODE></P>
  48
  49
  50     <H3>The options</H3>
  51
  52     <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
  53         <TR>
  54           <TH>Option</TH>
  55           <TH>Description</TH>
  56         </TR>
  57         <!-- <TR NAME="CECDispatching"> -->
  58         <TR>
  59           <TD><CODE>-CECDispatching</CODE>
  60             <EM>dispatching_strategy</EM>
  61           </TD>
  62           <TD>Select the dispatching strategy used by the COS
  63             event service. A <EM>reactive</EM> strategy will use the
  64             same thread that received the event from the supplier to
  65             push the event to all the consumers.
  66             The <EM>mt</EM> strategy will also use a pool of threads,
  67             but the thread to dispatch is randomly selected.
  68           </TD>
  69         </TR>
  70
  71         <!-- <TR NAME="CECDispatchingThreads"> -->
  72         <TR>
  73           <TD><CODE>-CECDispatchingThreads</CODE>
  74             <EM>number_of_threads</EM>
  75           </TD>
  76           <TD>Select the number of threads used by the <EM>mt</EM>
  77             dispatching strategy.
  78           </TD>
  79         </TR>
  80
  81         <!-- <TR NAME="CECProxyConsumerLock"> -->
  82         <TR>
  83           <TD><CODE>-CECProxyConsumerLock</CODE>
  84             <EM>lock_type</EM>
  85           </TD>
  86           <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or
  87             <EM>recursive</EM>) to synchronize access to the
  88             ProxyPushConsumer state.
  89           </TD>
  90         </TR>
  91
  92         <!-- <TR NAME="CECProxySupplierLock"> -->
  93         <TR>
  94           <TD><CODE>-CECProxySupplierLock</CODE>
  95             <EM>lock_type</EM>
  96           </TD>
  97           <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or
  98             <EM>recursive</EM>) to synchronize access to the
  99             ProxyPushSupplier state.
 100           </TD>
 101         </TR>
 102
 103         <!-- <TR NAME="CECUseORBId"> -->
 104         <TR>
 105           <TD><CODE>-CECUseORBId</CODE>
 106             <EM>orbid</EM>
 107           </TD>
 108           <TD>Set the name of the ORB used by the event service, only
 109             useful in applications that create multiple ORBs and
 110             activate the event service in one of them.
 111           </TD>
 112         </TR>
 113
 114         <!-- <TR NAME="CECConsumerControl"> -->
 115         <TR>
 116           <TD><CODE>-CECConsumerControl</CODE>
 117             <EM>policy</EM>
 118           </TD>
 119           <TD>Select the consumer control policy (<EM>null</EM> or
 120             <EM>reactive</EM>) to detect and discard broken consumers.
 121           </TD>
 122         </TR>
 123
 124         <!-- <TR NAME="CECSupplierControl"> -->
 125         <TR>
 126           <TD><CODE>-CECSupplierControl</CODE>
 127             <EM>policy</EM>
 128           </TD>
 129           <TD>Select the supplier control policy (<EM>null</EM> or
 130             <EM>reactive</EM>) to detect and discard broken suppliers.
 131           </TD>
 132         </TR>
 133
 134         <!-- <TR NAME="CECConsumerControlPeriod"> -->
 135         <TR>
 136           <TD><CODE>-CECConsumerControlPeriod</CODE>
 137             <EM>period</EM>
 138           </TD>
 139           <TD>Set the period (in microseconds) used by the reactive
 140             consumer control policy to poll the state of the
 141             consumers.
 142           </TD>
 143         </TR>
 144
 145         <!-- <TR NAME="CECSupplierControlPeriod"> -->
 146         <TR>
 147           <TD><CODE>-CECSupplierControlPeriod</CODE>
 148             <EM>period</EM>
 149           </TD>
 150           <TD>Set the period (in microseconds) used by the reactive
 151             supplier control policy to poll the state of the
 152             suppliers.
 153           </TD>
 154         </TR>
 155
 156         <!-- <TR NAME="CECConsumerControlTimeout"> -->
 157         <TR>
 158           <TD><CODE>-CECConsumerControlTimeout</CODE>
 159             <EM>timeout</EM>
 160           </TD>
 161           <TD><P>Set the relative roundtrip timeout for push and pull
 162                  consumers.  The default is 10000 microseconds.
 163                  This relative roundtrip timeout is utilized
 164                  when each consumer attached to the supplier is queried.
 165                  If querying any one of the consumers times out, it may
 166                  be disconnected depending on the
 167                  -CECProxyDisconnectRetries setting.
 168               </P>
 169               <P>This option can also be referenced as
 170                  -CECConsumerControlRoundtripTimeout.
 171              </P>
 172          </TD>
 173         </TR>
 174
 175         <!-- <TR NAME="CECSupplierControlTimeout"> -->
 176         <TR>
 177           <TD><CODE>-CECSupplierControlTimeout</CODE>
 178             <EM>timeout</EM>
 179           </TD>
 180           <TD><P>Set the relative roundtrip timeout for push or pull
 181                  suppliers.  The default is 10000 microseconds.
 182                  This relative roundtrip timeout is utilized
 183                  when each supplier attached to the consumer is queried.
 184                  If querying any one of the suppliers times out, it may
 185                  be disconnected depending on the
 186                  -CECProxyDisconnectRetries setting.
 187               </P>
 188               <P>This option can also be referenced as
 189                  -CECSupplierControlRoundtripTimeout.
 190              </P>
 191          </TD>
 192         </TR>
 193
 194         <!-- <TR NAME="CECReactivePullingPeriod"> -->
 195         <TR>
 196           <TD><CODE>-CECReactivePullingPeriod</CODE>
 197             <EM>period</EM>
 198           </TD>
 199           <TD>Set the period (in microseconds) used by the reactive
 200             pulling strategy to poll all the PullSuppliers for an
 201             event.
 202           </TD>
 203         </TR>
 204
 205         <!-- <TR NAME="CECConsumerOperationTimeout"> -->
 206         <TR>
 207           <TD><CODE>-CECConsumerOperationTimeout</CODE>
 208             <EM>timeout</EM>
 209           </TD>
 210           <TD>Set the relative roundtrip timeout for all operations (except
 211             &quot;pings&quot; due to reactive consumer control) on consumers.
 212             Reactive consumer control must be enabled for this option to take
 213             effect.  The units for <EM>timeout</EM> are microseconds.
 214             If a remote operation invoked on the consumer exceeds the timeout,
 215             then that consumer will be considered &quot;bad&quot; and will be
 216             disconnected from the event channel.
 217           </TD>
 218         </TR>
 219
 220         <!-- <TR NAME="CECSupplierOperationTimeout"> -->
 221         <TR>
 222           <TD><CODE>-CECSupplierOperationTimeout</CODE>
 223             <EM>timeout</EM>
 224           </TD>
 225           <TD>Set the relative roundtrip timeout for all operations (except
 226             &quot;pings&quot; due to reactive supplier control) on suppliers.
 227             Reactive supplier control must be enabled for this option to take
 228             effect.  The units for <EM>timeout</EM> are microseconds.
 229             If a remote operation invoked on the supplier exceeds the timeout
 230             then that supplier will be considered &quot;bad&quot; and will be
 231             disconnected from the event channel.
 232           </TD>
 233         </TR>
 234
 235         <!-- <TR NAME="CECProxyConsumerCollection"> -->
 236         <TR>
 237           <TD><CODE>-CECProxyConsumerCollection</CODE>
 238             <EM>flag[:flags]</EM>
 239           </TD>
 240           <TD><P>Configure the data structure and strategies used to
 241               implement collections of
 242               <CODE>ProxyPushConsumers</CODE> and
 243               <CODE>ProxyPullConsumers</CODE>.
 244               The argument is a colon separated list of flags, with
 245               the following semantics:
 246               <TABLE BORDER="1" CELLSPACING="2" CELLPADDING="0">
 247               <TR><TH>Flag</TH><TH>Description</TH>
 248               </TR>
 249               <TR>
 250                 <TD>MT</TD>
 251                 <TD>Use regular mutexes and/or condition
 252                   variables for serialization.
 253                 </TD>
 254                 </tr>
 255               <TR>
 256                 <TD>ST</TD>
 257                 <TD>Use null mutexes and/or condition
 258                   variables for serialization.
 259                 </TD>
 260                 </tr>
 261               <TR>
 262                 <TD>LIST</TD>
 263                 <TD>Implement the collection using an ordered list,
 264                   fast for iteration (i.e. during event dispatching),
 265                   but slow for insertion and removal (i.e. when
 266                   clients connect and disconnect from the EC).
 267                 </TD>
 268                 </tr>
 269               <TR>
 270                 <TD>RB_TREE</TD>
 271                 <TD>Implement the collection using a Red-Black tree,
 272                   slow for iteration (i.e. during event dispatching),
 273                   but fast for insertion and removal (i.e. when
 274                   clients connect and disconnect from the EC).
 275                 </TD>
 276                 </tr>
 277               <TR>
 278                 <TD>IMMEDIATE</TD>
 279                 <TD>Threads block until they can execute a change on
 280                   the data structure, the system must use other
 281                   approaches to guarantee that the iterators are not
 282                   invalidated during event dispatching.  For example,
 283                   use a separate dispatching thread.  Using this option
 284                   with the reactive values for any of the
 285                   -CECSupplierControl, -CECConsumerControl, or
 286                   -CECDispatching options may cause deadlocks.
 287                 </TD>
 288                 </tr>
 289               <TR>
 290                 <TD>COPY_ON_READ</TD>
 291                 <TD>Before initiating an iteration to dispatch events
 292                   (or similar tasks) a copy of the complete collection
 293                   is performed.
 294                   This solves most of the synchronization problems,
 295                   but introduces a significant source of overhead and
 296                   priority inversions on the critical path.
 297                 </TD>
 298                 </tr>
 299               <TR>
 300                 <TD>COPY_ON_WRITE</TD>
 301                 <TD>Similar to the previous one, but the copy is only
 302                   performed when needed.
 303                 </TD>
 304                 </tr>
 305               <TR>
 306                 <TD>DELAYED</TD>
 307                 <TD>Threads that need to change the collection can
 308                   detect if that change will invalidate iterators used
 309                   by other threads.
 310                   If so, the thread posts the change on a queue that
 311                   is executed once the collection is no longer in
 312                   use.
 313                 </TD>
 314               </TR>
 315               </TABLE>
 316             </P>
 317           </TD>
 318         </TR>
 319
 320         <!-- <TR NAME="CECProxySupplierCollection"> -->
 321         <TR>
 322           <TD><CODE>-CECProxySupplierCollection</CODE>
 323             <EM>flag[:flags]</EM>
 324           </TD>
 325           <TD><P>Configure the data structure and strategies used to
 326               implement collections of <CODE>ProxyPushSupplier</CODE>
 327               and <CODE>ProxyPullSupplier</CODE> objects.
 328               Use the same arguments as with the
 329               <CODE>CECProxyConsumerCollection</CODE> option.
 330             </P>
 331          </TD>
 332         </TR>
 333
 334         <!-- <TR NAME="CECProxyDisconnectRetries"> -->
 335         <TR>
 336           <TD><CODE>-CECProxyDisconnectRetries</CODE>
 337             <EM>number of retries</EM>
 338           </TD>
 339           <TD><P>This determines the number of times a consumer or
 340                  supplier can be "unresponsive" before the supplier or
 341                  consumer control will disconnect it.  The default is zero
 342                  retries.
 343             </P>
 344          </TD>
 345         </TR>
 346
 347         <!-- <TR NAME="CECProxyDisconnectRetries"> -->
 348         <TR>
 349           <TD><CODE>-CECShutdownWaitCompletion</CODE>
 350             <EM>true|false</EM>
 351           </TD>
 352           <TD><P>Default <CODE>true</CODE> which means we wait on all events in the queue
 353           to be processed on shutdown, in case of <CODE>false</CODE> all pending events in the queue are flushed
 354           on shutdown.
 355             </P>
 356          </TD>
 357         </TR>
 358
 359       </TABLE>
 360     </P>
 361
 362     <H3>The constructor</H3>
 363
 364     <P>The <CODE>TAO_CEC_EventChannel</CODE> class implements the
 365       <CODE>CosEventChannelAdmin::EventChannel</CODE> interface;
 366       this class takes one mandatory and two optional parameters in
 367       its constructor:
 368     </P>
 369
 370 <PRE>
 371   TAO_CEC_EventChannel (const TAO_CEC_EventChannel_Attributes& attributes,
 372                         TAO_CEC_Factory* factory = 0,
 373                         int own_factory = 0);
 374 </PRE>
 375
 376     <P>The <CODE>factory</CODE> is an optional parameter to override
 377       the default strategy factory used by the event channel,
 378       the event channel will destroy the factory if the
 379       <CODE>own_factory</CODE> argument is true.
 380     </P>
 381
 382     <P>The <CODE>attributes</CODE> parameter can be used to fine tune
 383       some of the algorithms and strategies used by the event channel,
 384       the default values are probably OK for most applications.
 385       Notice that the attributes include the POA used to activate the
 386       ConsumerAdmin, SupplierAdmin, ProxyPushConsumer,
 387       ProxyPushSupplier, ProxyPullConsumer and the ProxyPullSupplier
 388       objects;
 389       these POAs must have the <CODE>IMPLICIT_ACTIVATION</CODE> and the
 390       <CODE>SYSTEM_ID</CODE> policies (as the RootPOA does).
 391     </P>
 392
 393     <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
 394         <TR><TH>Attribute</TH><TH>Description</TH></TR>
 395
 396         <TR><TD><CODE>consumer_reconnect</CODE></TD>
 397           <TD>If the attribute is not zero then the same consumer can
 398             call <CODE>connect_push_consumer</CODE> on its
 399             ProxyPushSupplier multiple times to change its
 400             subscriptions;
 401             this is usually more efficient that disconnecting and
 402             connecting again.
 403           </TD>
 404         </TR>
 405
 406         <TR><TD><CODE>supplier_reconnect</CODE></TD>
 407           <TD>If the attribute is not zero then the same supplier can
 408             call <CODE>connect_push_supplier</CODE> on its
 409             ProxyPushConsumer multiple times to change its
 410             publications;
 411             this is usually more efficient that disconnecting and
 412             connecting again.
 413           </TD>
 414         </TR>
 415
 416         <TR><TD><CODE>disconnect_callbacks</CODE></TD>
 417           <TD>It not zero the event channel will send disconnect
 418             callbacks when a disconnect method is called on a Proxy.
 419             In other words, if a consumer calls
 420             <CODE>disconnect_push_supplier()</CODE> on its proxy the
 421             EC will invoke <CODE>disconnect_push_consumer()</CODE>
 422             on the consumer.  A similar thing is done for suppliers.
 423             It is a matter of debate what the spec requires for the
 424             regular event service.
 425           </TD>
 426         </TR>
 427
 428         <TR><TD><CODE>busy_hwm</CODE></TD>
 429           <TD>When the delayed flag is set on proxy collections,
 430             this flag controls the maximum
 431             number of threads that can simultaneously iterate over the
 432             collection before blocking.
 433             It can be used to avoid starvation in delayed updates on
 434             the collection.
 435           </TD>
 436         </TR>
 437
 438         <TR><TD><CODE>max_write_delay</CODE></TD>
 439           <TD>When the delayed flag is set on proxy collections,
 440             this flag controls the maximum
 441             number of threads that will initiate dispatching
 442             <B>after</B> a change has been posted.
 443             Any thread after that is blocked until the operations are
 444             performed.
 445             It can be used to completely stop starvation of delayed
 446             updates on the collection.
 447           </TD>
 448         </TR>
 449
 450         <TR><TD><CODE>supplier_poa</CODE></TD>
 451           <TD>The POA used by the event channel to activate SupplierAdmin
 452             and SupplierProxy objects.
 453           </TD>
 454         </TR>
 455
 456         <TR><TD><CODE>consumer_poa</CODE></TD>
 457           <TD>The POA used by the event channel to activate ConsumerAdmin
 458             and ConsumerProxy objects.
 459           </TD>
 460         </TR>
 461
 462       </TABLE>
 463     </P>
 464
 465     <P><HR><P>
 466
 467       Back to the TAO <A HREF="index.html">components documentation</A>.
 468   </body>
 469 </html>