diff options
Diffstat (limited to 'TAO/docs/cec_options.html')
| -rw-r--r-- | TAO/docs/cec_options.html | 464 |
1 files changed, 464 insertions, 0 deletions
diff --git a/TAO/docs/cec_options.html b/TAO/docs/cec_options.html new file mode 100644 index 00000000000..a1109db123d --- /dev/null +++ b/TAO/docs/cec_options.html @@ -0,0 +1,464 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>COS Event Channel Configuration</title> + <!-- $Id$ --> + </head> + + <body> + <CENTER> + <h1>COS Event Channel Configuration</h1> + </CENTER> + + <H3>Run-time Configuration</H3> + + <P>The new implementation of the COS Event Service uses a + factory to build all the objects and strategies it requires. + The factory can be dynamically loaded using ACE Service + Configurator, this is extremely convenient because the factory + can also parse options in the Service Configurator script file. + </P> + + <P>The current implementation provides a default implementation + for this Factory, this document describes the options used by + this default implementation. + Users can define their own implementation, with new ad-hoc + strategies or with pre-selected strategies. + </P> + + <H3>The configuration file</H3> + + <P>The COS channel uses the same service configurator + file that the ORB uses, the default name for this file is + <CODE>svc.conf</CODE>, but the ORB option + <CODE>-ORBSvcConf</CODE> can be used to override this. + The format of the file is described in detail in + the service configurator documentation, but the relevant section + for the event channel looks like this: + </P> + +<PRE> +# Comments go here... +# More comments if you want to... +static CEC_Factory "-CECDispatching reactive ....." +</PRE> + + <P>All the event service factory options start with + <CODE>-CEC</CODE></P> + + + <H3>The options</H3> + + <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> + <TR> + <TH>Option</TH> + <TH>Description</TH> + </TR> + <!-- <TR NAME="CECDispatching"> --> + <TR> + <TD><CODE>-CECDispatching</CODE> + <EM>dispatching_strategy</EM> + </TD> + <TD>Select the dispatching strategy used by the COS + event service. A <EM>reactive</EM> strategy will use the + same thread that received the event from the supplier to + push the event to all the consumers. + The <EM>mt</EM> strategy will also use a pool of threads, + but the thread to dispatch is randomly selected. + </TD> + </TR> + + <!-- <TR NAME="CECDispatchingThreads"> --> + <TR> + <TD><CODE>-CECDispatchingThreads</CODE> + <EM>number_of_threads</EM> + </TD> + <TD>Select the number of threads used by the <EM>mt</EM> + dispatching strategy. + </TD> + </TR> + + <!-- <TR NAME="CECProxyConsumerLock"> --> + <TR> + <TD><CODE>-CECProxyConsumerLock</CODE> + <EM>lock_type</EM> + </TD> + <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or + <EM>recursive</EM>) to synchronize access to the + ProxyPushConsumer state. + </TD> + </TR> + + <!-- <TR NAME="CECProxySupplierLock"> --> + <TR> + <TD><CODE>-CECProxySupplierLock</CODE> + <EM>lock_type</EM> + </TD> + <TD>Select the lock type (<EM>null</EM>, <EM>thread</EM> or + <EM>recursive</EM>) to synchronize access to the + ProxyPushSupplier state. + </TD> + </TR> + + <!-- <TR NAME="CECUseORBId"> --> + <TR> + <TD><CODE>-CECUseORBId</CODE> + <EM>orbid</EM> + </TD> + <TD>Set the name of the ORB used by the event service, only + useful in applications that create multiple ORBs and + activate the event service in one of them. + </TD> + </TR> + + <!-- <TR NAME="CECConsumerControl"> --> + <TR> + <TD><CODE>-CECConsumerControl</CODE> + <EM>policy</EM> + </TD> + <TD>Select the consumer control policy (<EM>null</EM> or + <EM>reactive</EM>) to detect and discard broken consumers. + </TD> + </TR> + + <!-- <TR NAME="CECSupplierControl"> --> + <TR> + <TD><CODE>-CECSupplierControl</CODE> + <EM>policy</EM> + </TD> + <TD>Select the supplier control policy (<EM>null</EM> or + <EM>reactive</EM>) to detect and discard broken suppliers. + </TD> + </TR> + + <!-- <TR NAME="CECConsumerControlPeriod"> --> + <TR> + <TD><CODE>-CECConsumerControlPeriod</CODE> + <EM>period</EM> + </TD> + <TD>Set the period (in microseconds) used by the reactive + consumer control policy to poll the state of the + consumers. + </TD> + </TR> + + <!-- <TR NAME="CECSupplierControlPeriod"> --> + <TR> + <TD><CODE>-CECSupplierControlPeriod</CODE> + <EM>period</EM> + </TD> + <TD>Set the period (in microseconds) used by the reactive + supplier control policy to poll the state of the + suppliers. + </TD> + </TR> + + <!-- <TR NAME="CECConsumerControlTimeout"> --> + <TR> + <TD><CODE>-CECConsumerControlTimeout</CODE> + <EM>timeout</EM> + </TD> + <TD><P>Set the relative roundtrip timeout for push and pull + consumers. The default is 10000 microseconds. + This relative roundtrip timeout is utilized + when each consumer attached to the supplier is queried. + If querying any one of the consumers times out, it may + be disconnected depending on the + -CECProxyDisconnectRetries setting. + </P> + <P>This option can also be referenced as + -CECConsumerControlRoundtripTimeout. + </P> + </TD> + </TR> + + <!-- <TR NAME="CECSupplierControlTimeout"> --> + <TR> + <TD><CODE>-CECSupplierControlTimeout</CODE> + <EM>timeout</EM> + </TD> + <TD><P>Set the relative roundtrip timeout for push or pull + suppliers. The default is 10000 microseconds. + This relative roundtrip timeout is utilized + when each supplier attached to the consumer is queried. + If querying any one of the suppliers times out, it may + be disconnected depending on the + -CECProxyDisconnectRetries setting. + </P> + <P>This option can also be referenced as + -CECSupplierControlRoundtripTimeout. + </P> + </TD> + </TR> + + <!-- <TR NAME="CECReactivePullingPeriod"> --> + <TR> + <TD><CODE>-CECReactivePullingPeriod</CODE> + <EM>period</EM> + </TD> + <TD>Set the period (in microseconds) used by the reactive + pulling strategy to poll all the PullSuppliers for an + event. + </TD> + </TR> + + <!-- <TR NAME="CECConsumerOperationTimeout"> --> + <TR> + <TD><CODE>-CECConsumerOperationTimeout</CODE> + <EM>timeout</EM> + </TD> + <TD>Set the relative roundtrip timeout for all operations (except + "pings" due to reactive consumer control) on consumers. + Reactive consumer control must be enabled for this option to take + effect. The units for <EM>timeout</EM> are microseconds. + If a remote operation invoked on the consumer exceeds the timeout, + then that consumer will be considered "bad" and will be + disconnected from the event channel. + </TD> + </TR> + + <!-- <TR NAME="CECSupplierOperationTimeout"> --> + <TR> + <TD><CODE>-CECSupplierOperationTimeout</CODE> + <EM>timeout</EM> + </TD> + <TD>Set the relative roundtrip timeout for all operations (except + "pings" due to reactive supplier control) on suppliers. + Reactive supplier control must be enabled for this option to take + effect. The units for <EM>timeout</EM> are microseconds. + If a remote operation invoked on the supplier exceeds the timeout + then that supplier will be considered "bad" and will be + disconnected from the event channel. + </TD> + </TR> + + <!-- <TR NAME="CECProxyConsumerCollection"> --> + <TR> + <TD><CODE>-CECProxyConsumerCollection</CODE> + <EM>flag[:flags]</EM> + </TD> + <TD><P>Configure the data structure and strategies used to + implement collections of + <CODE>ProxyPushConsumers</CODE> and + <CODE>ProxyPullConsumers</CODE>. + The argument is a colon separated list of flags, with + the following semantics: + <TABLE BORDER="1" CELLSPACING="2" CELLPADDING="0"> + <TR><TH>Flag</TH><TH>Description</TH> + </TR> + <TR> + <TD>MT</TD> + <TD>Use regular mutexes and/or condition + variables for serialization. + </TD> + </tr> + <TR> + <TD>ST</TD> + <TD>Use null mutexes and/or condition + variables for serialization. + </TD> + </tr> + <TR> + <TD>LIST</TD> + <TD>Implement the collection using an ordered list, + fast for iteration (i.e. during event dispatching), + but slow for insertion and removal (i.e. when + clients connect and disconnect from the EC). + </TD> + </tr> + <TR> + <TD>RB_TREE</TD> + <TD>Implement the collection using a Red-Black tree, + slow for iteration (i.e. during event dispatching), + but fast for insertion and removal (i.e. when + clients connect and disconnect from the EC). + </TD> + </tr> + <TR> + <TD>IMMEDIATE</TD> + <TD>Threads block until they can execute a change on + the data structure, the system must use other + approaches to guarantee that the iterators are not + invalidated during event dispatching. For example, + use a separate dispatching thread. Using this option + with the reactive values for any of the + -CECSupplierControl, -CECConsumerControl, or + -CECDispatching options may cause deadlocks. + </TD> + </tr> + <TR> + <TD>COPY_ON_READ</TD> + <TD>Before initiating an iteration to dispatch events + (or similar tasks) a copy of the complete collection + is performed. + This solves most of the synchronization problems, + but introduces a significant source of overhead and + priority inversions on the critical path. + </TD> + </tr> + <TR> + <TD>COPY_ON_WRITE</TD> + <TD>Similar to the previous one, but the copy is only + performed when needed. + </TD> + </tr> + <TR> + <TD>DELAYED</TD> + <TD>Threads that need to change the collection can + detect if that change will invalidate iterators used + by other threads. + If so, the thread posts the change on a queue that + is executed once the collection is no longer in + use. + </TD> + </TR> + </TABLE> + </P> + </TD> + </TR> + + <!-- <TR NAME="CECProxySupplierCollection"> --> + <TR> + <TD><CODE>-CECProxySupplierCollection</CODE> + <EM>flag[:flags]</EM> + </TD> + <TD><P>Configure the data structure and strategies used to + implement collections of <CODE>ProxyPushSupplier</CODE> + and <CODE>ProxyPullSupplier</CODE> objects. + Use the same arguments as with the + <CODE>CECProxyConsumerCollection</CODE> option. + </P> + </TD> + </TR> + + <!-- <TR NAME="CECProxyDisconnectRetries"> --> + <TR> + <TD><CODE>-CECProxyDisconnectRetries</CODE> + <EM>number of retries</EM> + </TD> + <TD><P>This determines the number of times a consumer or + supplier can be "unresponsive" before the supplier or + consumer control will disconnect it. The default is zero + retries. + </P> + </TD> + </TR> + </TABLE> + </P> + + <H3>The constructor</H3> + + <P>The <CODE>TAO_CEC_EventChannel</CODE> class implements the + <CODE>CosEventChannelAdmin::EventChannel</CODE> interface; + this class takes one mandatory and two optional parameters in + its constructor: + </P> + +<PRE> + TAO_CEC_EventChannel (const TAO_CEC_EventChannel_Attributes& attributes, + TAO_CEC_Factory* factory = 0, + int own_factory = 0); +</PRE> + + <P>The <CODE>factory</CODE> is an optional parameter to override + the default strategy factory used by the event channel, + the event channel will destroy the factory if the + <CODE>own_factory</CODE> argument is true. + </P> + + <P>The <CODE>attributes</CODE> parameter can be used to fine tune + some of the algorithms and strategies used by the event channel, + the default values are probably OK for most applications. + Notice that the attributes include the POA used to activate the + ConsumerAdmin, SupplierAdmin, ProxyPushConsumer, + ProxyPushSupplier, ProxyPullConsumer and the ProxyPullSupplier + objects; + these POAs must have the <CODE>IMPLICIT_ACTIVATION</CODE> and the + <CODE>SYSTEM_ID</CODE> policies (as the RootPOA does). + </P> + + <P><TABLE BORDER="2" CELLSPACING="2" CELLPADDING="0"> + <TR><TH>Attribute</TH><TH>Description</TH></TR> + + <TR><TD><CODE>consumer_reconnect</CODE></TD> + <TD>If the attribute is not zero then the same consumer can + call <CODE>connect_push_consumer</CODE> on its + ProxyPushSupplier multiple times to change its + subscriptions; + this is usually more efficient that disconnecting and + connecting again. + </TD> + </TR> + + <TR><TD><CODE>supplier_reconnect</CODE></TD> + <TD>If the attribute is not zero then the same supplier can + call <CODE>connect_push_supplier</CODE> on its + ProxyPushConsumer multiple times to change its + publications; + this is usually more efficient that disconnecting and + connecting again. + </TD> + </TR> + + <TR><TD><CODE>disconnect_callbacks</CODE></TD> + <TD>It not zero the event channel will send disconnect + callbacks when a disconnect method is called on a Proxy. + In other words, if a consumer calls + <CODE>disconnect_push_supplier()</CODE> on its proxy the + EC will invoke <CODE>disconnect_push_consumer()</CODE> + on the consumer. A similar thing is done for suppliers. + It is a matter of debate what the spec requires for the + regular event service. + </TD> + </TR> + + <TR><TD><CODE>busy_hwm</CODE></TD> + <TD>When the delayed flag is set on proxy collections, + this flag controls the maximum + number of threads that can simultaneously iterate over the + collection before blocking. + It can be used to avoid starvation in delayed updates on + the collection. + </TD> + </TR> + + <TR><TD><CODE>max_write_delay</CODE></TD> + <TD>When the delayed flag is set on proxy collections, + this flag controls the maximum + number of threads that will initiate dispatching + <B>after</B> a change has been posted. + Any thread after that is blocked until the operations are + performed. + It can be used to completely stop starvation of delayed + updates on the collection. + </TD> + </TR> + + <TR><TD><CODE>supplier_poa</CODE></TD> + <TD>The POA used by the event channel to activate SupplierAdmin + and SupplierProxy objects. + </TD> + </TR> + + <TR><TD><CODE>consumer_poa</CODE></TD> + <TD>The POA used by the event channel to activate ConsumerAdmin + and ConsumerProxy objects. + </TD> + </TR> + + </TABLE> + </P> + + <P><HR><P> + + Back to the TAO <A HREF="index.html">components documentation</A>. + + <!--#include virtual="/~schmidt/cgi-sig.html" --> + + <address><a href="mailto:coryan@cs.wustl.edu">Carlos O'Ryan</a></address> +<!-- Created: Thu Jul 1 21:44:28 CDT 1999 --> +<!-- hhmts start --> +Last modified: Fri Apr 20 15:24:09 CDT 2001 +<!-- hhmts end --> + </body> +</html> |