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       </TABLE>
 347     </P>
 348
 349     <H3>The constructor</H3>
 350
 351     <P>The <CODE>TAO_CEC_EventChannel</CODE> class implements the
 352       <CODE>CosEventChannelAdmin::EventChannel</CODE> interface;
 353       this class takes one mandatory and two optional parameters in
 354       its constructor:
 355     </P>
 356
 357 <PRE>
 358   TAO_CEC_EventChannel (const TAO_CEC_EventChannel_Attributes& attributes,
 359                         TAO_CEC_Factory* factory = 0,
 360                         int own_factory = 0);
 361 </PRE>
 362
 363     <P>The <CODE>factory</CODE> is an optional parameter to override
 364       the default strategy factory used by the event channel,
 365       the event channel will destroy the factory if the
 366       <CODE>own_factory</CODE> argument is true.
 367     </P>
 368
 369     <P>The <CODE>attributes</CODE> parameter can be used to fine tune
 370       some of the algorithms and strategies used by the event channel,
 371       the default values are probably OK for most applications.
 372       Notice that the attributes include the POA used to activate the
 373       ConsumerAdmin, SupplierAdmin, ProxyPushConsumer,
 374       ProxyPushSupplier, ProxyPullConsumer and the ProxyPullSupplier
 375       objects;
 376       these POAs must have the <CODE>IMPLICIT_ACTIVATION</CODE> and the
 377       <CODE>SYSTEM_ID</CODE> policies (as the RootPOA does).
 378     </P>
 379
 380     <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0">
 381         <TR><TH>Attribute</TH><TH>Description</TH></TR>
 382
 383         <TR><TD><CODE>consumer_reconnect</CODE></TD>
 384           <TD>If the attribute is not zero then the same consumer can
 385             call <CODE>connect_push_consumer</CODE> on its
 386             ProxyPushSupplier multiple times to change its
 387             subscriptions;
 388             this is usually more efficient that disconnecting and
 389             connecting again.
 390           </TD>
 391         </TR>
 392
 393         <TR><TD><CODE>supplier_reconnect</CODE></TD>
 394           <TD>If the attribute is not zero then the same supplier can
 395             call <CODE>connect_push_supplier</CODE> on its
 396             ProxyPushConsumer multiple times to change its
 397             publications;
 398             this is usually more efficient that disconnecting and
 399             connecting again.
 400           </TD>
 401         </TR>
 402
 403         <TR><TD><CODE>disconnect_callbacks</CODE></TD>
 404           <TD>It not zero the event channel will send disconnect
 405             callbacks when a disconnect method is called on a Proxy.
 406             In other words, if a consumer calls
 407             <CODE>disconnect_push_supplier()</CODE> on its proxy the
 408             EC will invoke <CODE>disconnect_push_consumer()</CODE>
 409             on the consumer.  A similar thing is done for suppliers.
 410             It is a matter of debate what the spec requires for the
 411             regular event service.
 412           </TD>
 413         </TR>
 414
 415         <TR><TD><CODE>busy_hwm</CODE></TD>
 416           <TD>When the delayed flag is set on proxy collections,
 417             this flag controls the maximum
 418             number of threads that can simultaneously iterate over the
 419             collection before blocking.
 420             It can be used to avoid starvation in delayed updates on
 421             the collection.
 422           </TD>
 423         </TR>
 424
 425         <TR><TD><CODE>max_write_delay</CODE></TD>
 426           <TD>When the delayed flag is set on proxy collections,
 427             this flag controls the maximum
 428             number of threads that will initiate dispatching
 429             <B>after</B> a change has been posted.
 430             Any thread after that is blocked until the operations are
 431             performed.
 432             It can be used to completely stop starvation of delayed
 433             updates on the collection.
 434           </TD>
 435         </TR>
 436
 437         <TR><TD><CODE>supplier_poa</CODE></TD>
 438           <TD>The POA used by the event channel to activate SupplierAdmin
 439             and SupplierProxy objects.
 440           </TD>
 441         </TR>
 442
 443         <TR><TD><CODE>consumer_poa</CODE></TD>
 444           <TD>The POA used by the event channel to activate ConsumerAdmin
 445             and ConsumerProxy objects.
 446           </TD>
 447         </TR>
 448
 449       </TABLE>
 450     </P>
 451
 452     <P><HR><P>
 453
 454       Back to the TAO <A HREF="index.html">components documentation</A>.
 455   </body>
 456 </html>