Real-Time Event Channel Configuration

Configuring the Event Channel at Compilation Time

TAO's Real-Time Event Channel can be configured at compilation time to use a different payload than its default. To do so there are several options:

Run-time Configuration

The new implementation of the real-time event channel 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.

There are currently four implementations of the factory. The table below describes all of the options (and values) supported by these factories. The default factory supports all of the options below and most of the potential values, except as specifically indicated. The sched factory defines new option values as indicated below that allow the RTES to integrate with the Real-Time Scheduling Service. Use of the sched factory requires that you link in the TAO_RTSchedEvent library. The basic and null factories are hard-coded factories that do not support any configuration options. They both define simple configurations that may enable some applications to use the RTES in a smaller footprint. See the files $TAO_ROOT/orbsvcs/orbsvcs/Event/EC_Null_Factory.h and $TAO_ROOT/orbsvcs/orbsvcs/Event/EC_Basic_Factory.h for details.

The configuration file

The real-time event 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 EC_Factory "-ECFiltering basic ....."

All the event service factory options start with -EC

The options

Option Description
-ECDispatching dispatching_strategy Select the dispatching strategy used by the real-time event service. The reactive strategy uses the same thread that received the event from the supplier to push the event to all the consumers. The priority strategy (sched factory only) uses a prioritized pool of threads and queries the scheduling service to select the thread that dispatches each event. The mt strategy also uses a pool of threads, but the thread to dispatch is randomly selected.
-ECDispatchingThreads number_of_threads Select the number of threads used by the mt dispatching strategy.
-ECFiltering consumer_filtering_strategy Select the filtering strategy used by the consumers. The null filtering strategy will build trivial filters for all consumers. The basic filtering strategy supports disjunction, conjunction, logical and, negation, bitmask, and timeout filters based on the subscriptions passed by the consumer during the connect call. It only supports limited nesting of filter groups. The prefix filtering strategy supports all filter types that the basic strategy does and allows unlimited nesting of filter groups. When using the prefix strategy, the source field of the group filter must specify the number of children in the group. The priority filtering strategy (sched factory only) supports the same features as the basic filtering strategy, but it also collaborates with the scheduling service to build the dependency graph.
-ECSupplierFiltering supplier_filtering_strategy The event channel can also perform some filtering close to the suppliers by minimizing the number of consumers that are tested for given event. If the strategy is null then a global collection of consumers is maintained and each event is filtered by each consumer. If the strategy is per-supplier then the EC uses the supplier publications and the consumer subscriptions to determine which consumers could potentially be interested in events for each supplier. This set of consumers is usually smaller than the complete set and it is thus faster to traverse it, but keeping more collections of consumers increases the connection and disconnection time as well as the memory requirements.
-ECTimeout timeout_strategy A consumer can request that the event channel generate periodic or oneshot timeout events. This option controls the strategy to generate the timeouts, using reactive the same reactor used for the ORB is used by the event service. The priority strategy (sched factory only) uses a prioritized group of threads, timeouts with higher rate are generated by threads of higher priority.
NOTE: The priority strategy is not implemented
-ECObserver observer The event channel uses the Observer pattern to report changes in the subscriptions and publications of its suppliers and consumers; this is especially useful in the implementation of event channel gateways. The user can disable this feature by selecting the null strategy; whereas the basic strategy provides a simple, yet efficient implementation.
NOTE: The default is to have the feature disabled.
-ECScheduling scheduling_strategy The event channel can collaborate with the scheduling service to build the dependency list between the consumers and the suppliers. If the null scheduling strategy is selected this feature is disabled, the priority strategy (sched factory only) enables this feature.
NOTE: The default is to have the feature disabled.
-ECProxyConsumerLock lock_type Select the lock type (null, thread or recursive) to synchronize access to the ProxyPushConsumer state.
-ECProxySupplierLock lock_type Select the lock type (null, thread or recursive) to synchronize access to the ProxyPushSupplier state.
-ECUseORBId 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.
-ECConsumerControl policy Select the consumer control policy (null or reactive) to detect and discard broken consumers.
-ECSupplierControl policy Select the supplier control policy (null or reactive) to detect and discard broken suppliers.
-ECConsumerControlPeriod period Set the period (in microseconds) used by the reactive consumer control policy to poll the state of the consumers.
-ECSupplierControlPeriod period Set the period (in microseconds) used by the reactive supplier control policy to poll the state of the suppliers.
-ECProxyPushConsumerCollection flag[:flags]

Configure the data structure and strategies used to implement collections of ProxyPushConsumers. The argument is a colon separated list of flags, with the following semantics:
FlagDescription
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 -ECSupplierControl, -ECConsumerControl, or -ECDispatching 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.

-ECProxyPushSupplierCollection flag[:flags]

Configure the data structure and strategies used to implement collections of ProxyPushSupplier objects. Use the same arguments as with the ECProxyPushConsumerCollection option.

-ECPushSupplierSet

Obsolete option, ignored.

-ECConsumerAdminLock Obsolete option, ignored in the current version.
-ECSupplierAdminLock Obsolete option, ignored in the current version.

The constructor

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

  TAO_EC_Event_Channel (const TAO_EC_Event_Channel_Attributes& attributes,
                        TAO_EC_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 and ProxyPushSupplier objects; these POAs must have the IMPLICIT_ACTIVATION and the SYSTEM_ID policies (as the RootPOA does).

AttributeDescription
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.
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.
scheduler Most configurations of the real-time event channel do not require an scheduler. If any of the strategies that require an scheduling service is selected then this attribute should be set appropiately.
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.
disconnect_callbacks If not zero, then the event channel sends disconnect callbacks when a disconnect method is called on a Proxy. For example, if a consumer calls disconnect_push_supplier() on its proxy the EC invokes disconnect_push_consumer() on the consumer. An analogous call is also made for suppliers when this attribute is set. By default, these callbacks are not made in this situation.


Back to the TAO components documentation.

Carlos O'Ryan
Last modified: Fri Apr 20 15:30:42 CDT 2001