COS Event Channel Configuration

Run-time Configuration

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.

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.

The configuration file

The COS channel uses the same service configurator file that the ORB uses, the default name for this file is svc.conf, but the ORB option -ORBSvcConf 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:

# Comments go here...
# More comments if you want to...
static CEC_Factory "-CECDispatching reactive ....."

All the event service factory options start with -CEC

The options

Option	Description
-CECDispatching dispatching_strategy	Select the dispatching strategy used by the COS event service. A reactive strategy will use the same thread that received the event from the supplier to push the event to all the consumers. The mt strategy will also use a pool of threads, but the thread to dispatch is randomly selected.
-CECDispatchingThreads number_of_threads	Select the number of threads used by the mt dispatching strategy.
-CECProxyConsumerLock lock_type	Select the lock type (null, thread or recursive) to synchronize access to the ProxyPushConsumer state.
-CECProxySupplierLock lock_type	Select the lock type (null, thread or recursive) to synchronize access to the ProxyPushSupplier state.
-CECUseORBId orbid	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.
-CECConsumerControl policy	Select the consumer control policy (null or reactive) to detect and discard broken consumers.
-CECSupplierControl policy	Select the supplier control policy (null or reactive) to detect and discard broken suppliers.
-CECConsumerControlPeriod period	Set the period (in microseconds) used by the reactive consumer control policy to poll the state of the consumers.
-CECSupplierControlPeriod period	Set the period (in microseconds) used by the reactive supplier control policy to poll the state of the suppliers.
-CECConsumerControlTimeout timeout	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. This option can also be referenced as -CECConsumerControlRoundtripTimeout.
-CECSupplierControlTimeout timeout	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. This option can also be referenced as -CECSupplierControlRoundtripTimeout.
-CECReactivePullingPeriod period	Set the period (in microseconds) used by the reactive pulling strategy to poll all the PullSuppliers for an event.
-CECConsumerOperationTimeout timeout	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 timeout 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.
-CECSupplierOperationTimeout timeout	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 timeout 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.
-CECProxyConsumerCollection flag[:flags]	Configure the data structure and strategies used to implement collections of ProxyPushConsumers and ProxyPullConsumers. The argument is a colon separated list of flags, with the following semantics: Flag Description MT Use regular mutexes and/or condition variables for serialization. ST Use null mutexes and/or condition variables for serialization. LIST 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). RB_TREE 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). IMMEDIATE 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. COPY_ON_READ 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. COPY_ON_WRITE Similar to the previous one, but the copy is only performed when needed. DELAYED 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.
-CECProxySupplierCollection flag[:flags]	Configure the data structure and strategies used to implement collections of ProxyPushSupplier and ProxyPullSupplier objects. Use the same arguments as with the CECProxyConsumerCollection option.
-CECProxyDisconnectRetries number of retries	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.

The constructor

The TAO_CEC_EventChannel class implements the CosEventChannelAdmin::EventChannel interface; this class takes one mandatory and two optional parameters in its constructor:

  TAO_CEC_EventChannel (const TAO_CEC_EventChannel_Attributes& attributes,
                        TAO_CEC_Factory* factory = 0,
                        int own_factory = 0);

The factory is an optional parameter to override the default strategy factory used by the event channel, the event channel will destroy the factory if the own_factory argument is true.

The attributes 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 IMPLICIT_ACTIVATION and the SYSTEM_ID policies (as the RootPOA does).

Attribute	Description
consumer_reconnect	If the attribute is not zero then the same consumer can call connect_push_consumer on its ProxyPushSupplier multiple times to change its subscriptions; this is usually more efficient that disconnecting and connecting again.
supplier_reconnect	If the attribute is not zero then the same supplier can call connect_push_supplier on its ProxyPushConsumer multiple times to change its publications; this is usually more efficient that disconnecting and connecting again.
disconnect_callbacks	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 disconnect_push_supplier() on its proxy the EC will invoke disconnect_push_consumer() 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.
busy_hwm	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.
max_write_delay	When the delayed flag is set on proxy collections, this flag controls the maximum number of threads that will initiate dispatching after 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.
supplier_poa	The POA used by the event channel to activate SupplierAdmin and SupplierProxy objects.
consumer_poa	The POA used by the event channel to activate ConsumerAdmin and ConsumerProxy objects.

Back to the TAO components documentation.