# 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.