ChangeLogTag: Sat Jun 07 08:50:12 UTC 2003 Johnny Willemsen <jwillemsen@remedy.nl>

1 files changed, 139 insertions, 154 deletions

diff --git a/TAO/orbsvcs/orbsvcs/Event_Utilities.h b/TAO/orbsvcs/orbsvcs/Event_Utilities.h
index 94d6dcd1a4f..3379ec51beb 100644
--- a/TAO/orbsvcs/orbsvcs/Event_Utilities.h
+++ b/TAO/orbsvcs/orbsvcs/Event_Utilities.h
@@ -1,18 +1,15 @@
 /* -*- C++ -*- */
-// $Id$
-
-// ============================================================================
-//
-// = LIBRARY
-//    ace ORB
-//
-// = FILENAME
-//    Event_Utilities
-//
-// = AUTHOR
-//    Tim Harrison (harrison@cs.wustl.edu)
-//
-// ============================================================================
+
+//=============================================================================
+/**
+ *  @file    Event_Utilities
+ *
+ *  $Id$
+ *
+ *  @author Tim Harrison (harrison@cs.wustl.edu)
+ */
+//=============================================================================
+
 
 #ifndef ACE_EVENT_UTILITIES_H
 #define ACE_EVENT_UTILITIES_H
@@ -24,137 +21,118 @@
 
 typedef void (*TAO_EC_Event_Initializer) (RtecEventComm::Event&);
 
+/**
+ * @class ACE_ConsumerQOS_Factory
+ *
+ * @brief Consumer QOS Factory.
+ *
+ * This class allows easy (free from CORBA IDL constraints)
+ * construction of RtecEventChannelAdmin::ConsumerQOS structures.
+ * = CORRELATIONS
+ * ACE_ConsumerQOS_Factory separates subscriptions into conjunction
+ * and disjunction groups.  A group can be thought of as a set of
+ * events inside parenthesis: (A+B+C), where A,B, and C are
+ * events.
+ * The following code would be used to represent (A+B) | (B+C):
+ * ACE_ConsumerQOS_Factor factory;
+ * factory.start_conjunction_group ();
+ * factory.insert (A);
+ * factory.insert (B);
+ * factory.start_conjunction_group ();
+ * factory.insert (B);
+ * factory.insert (C);
+ * The following code would be used to represent (A|B) | (B|C):
+ * ACE_ConsumerQOS_Factor factory;
+ * factory.start_disjunction_group ();
+ * factory.insert (A);
+ * factory.insert (B);
+ * factory.start_disjunction_group ();
+ * factory.insert (B);
+ * factory.insert (C);
+ * First, this may not seem to be initially useful, as (A|B) |
+ * (B|C) seems the same as A|B|C.  However, this form does have a
+ * significant use when deadline timers are specified (described
+ * below). Note that groups end with the next call to
+ * start_XX_group.  Groups are always OR'd together.  That is,
+ * there is no way to directly build (A|B|C) + (D|E|F).  You can
+ * always expand the previous statement to the OR of multiple ANDs.
+ * = TIMEOUTS
+ * There are two types of timeout types defined in
+ * Event_Service_Constants.h.
+ * ACE_ES_EVENT_INTERVAL_TIMEOUT - the consumer wants to receive a
+ * timeout every N seconds.
+ * ACE_ES_EVENT_DEADLINE_TIMEOUT - the consumer wants the timeout
+ * if and only if some dependencies are not resolved first.
+ * Using these timeouts with the correlations discussed above, we
+ * can construct four different timer semantics: Interval Timer,
+ * Deadline Timer, Interval Correlation, Deadline Correlation:
+ * Interval Timer:
+ * (A+B+C) | (D+E+F) | (G+H+I) | IntervalTimeout
+ * This registers to receive an interval timeout regardless of
+ * other dependencies.  Event if events occur, the interval
+ * timeout will still be sent.
+ * Deadline Timer:
+ * (A+B+C) | (D+E+F) | (G+H+I) | DeadlineTimeout
+ * This registers to receive the deadline timeout ONLY if no
+ * other events occur.  If a single event is sent to the
+ * consumer, the timer is cancelled and rescheduled.
+ * Deadline Correlation:
+ * (A+B+C) | (D+E+F) | (G+H+DeadlineTimeout)
+ * If G and H do not occur within DeadlineTimeout time, a
+ * deadline timeout is sent.  It is cancelled and rescheduled if G
+ * and H occur.
+ * Interval Correlation:
+ * (A+B+C) | (D+E+F) | (G+H+IntervalTimeout)
+ * G+H+IntervalTimeout are sent ONLY after all have occurred.  If
+ * G+H occur, they are queued until IntervalTimeout occurs.  If
+ * IntervalTimeout occurs, it is queued until G+H occur.
+ */
 class TAO_RTEvent_Export ACE_ConsumerQOS_Factory
 {
-  // = TITLE
-  //    Consumer QOS Factory.
-  //
-  // = DESCRIPTION
-  //
-  //    This class allows easy (free from CORBA IDL constraints)
-  //    construction of RtecEventChannelAdmin::ConsumerQOS structures.
-  //
-  // = CORRELATIONS
-  //
-  //    ACE_ConsumerQOS_Factory separates subscriptions into conjunction
-  //    and disjunction groups.  A group can be thought of as a set of
-  //    events inside parenthesis: (A+B+C), where A,B, and C are
-  //    events.
-  //
-  //    The following code would be used to represent (A+B) | (B+C):
-  //
-  //    ACE_ConsumerQOS_Factor factory;
-  //    factory.start_conjunction_group ();
-  //    factory.insert (A);
-  //    factory.insert (B);
-  //    factory.start_conjunction_group ();
-  //    factory.insert (B);
-  //    factory.insert (C);
-  //
-  //    The following code would be used to represent (A|B) | (B|C):
-  //
-  //    ACE_ConsumerQOS_Factor factory;
-  //    factory.start_disjunction_group ();
-  //    factory.insert (A);
-  //    factory.insert (B);
-  //    factory.start_disjunction_group ();
-  //    factory.insert (B);
-  //    factory.insert (C);
-  //
-  //    First, this may not seem to be initially useful, as (A|B) |
-  //    (B|C) seems the same as A|B|C.  However, this form does have a
-  //    significant use when deadline timers are specified (described
-  //    below). Note that groups end with the next call to
-  //    start_XX_group.  Groups are always OR'd together.  That is,
-  //    there is no way to directly build (A|B|C) + (D|E|F).  You can
-  //    always expand the previous statement to the OR of multiple ANDs.
-  //
-  // = TIMEOUTS
-  //
-  //    There are two types of timeout types defined in
-  //    Event_Service_Constants.h.
-  //
-  //    ACE_ES_EVENT_INTERVAL_TIMEOUT - the consumer wants to receive a
-  //    timeout every N seconds.
-  //
-  //    ACE_ES_EVENT_DEADLINE_TIMEOUT - the consumer wants the timeout
-  //    if and only if some dependencies are not resolved first.
-  //
-  //    Using these timeouts with the correlations discussed above, we
-  //    can construct four different timer semantics: Interval Timer,
-  //    Deadline Timer, Interval Correlation, Deadline Correlation:
-  //
-  //    Interval Timer:
-  //
-  //      (A+B+C) | (D+E+F) | (G+H+I) | IntervalTimeout
-  //
-  //      This registers to receive an interval timeout regardless of
-  //      other dependencies.  Event if events occur, the interval
-  //      timeout will still be sent.
-  //
-  //    Deadline Timer:
-  //
-  //      (A+B+C) | (D+E+F) | (G+H+I) | DeadlineTimeout
-  //
-  //      This registers to receive the deadline timeout ONLY if no
-  //      other events occur.  If a single event is sent to the
-  //      consumer, the timer is cancelled and rescheduled.
-  //
-  //    Deadline Correlation:
-  //
-  //      (A+B+C) | (D+E+F) | (G+H+DeadlineTimeout)
-  //
-  //      If G and H do not occur within DeadlineTimeout time, a
-  //      deadline timeout is sent.  It is cancelled and rescheduled if G
-  //      and H occur.
-  //
-  //    Interval Correlation:
-  //
-  //      (A+B+C) | (D+E+F) | (G+H+IntervalTimeout)
-  //
-  //      G+H+IntervalTimeout are sent ONLY after all have occurred.  If
-  //      G+H occur, they are queued until IntervalTimeout occurs.  If
-  //      IntervalTimeout occurs, it is queued until G+H occur.
 public:
+  /// Default construction.
   ACE_ConsumerQOS_Factory (TAO_EC_Event_Initializer initializer = 0);
-  // Default construction.
 
+  /// Death and destruction.
   ~ACE_ConsumerQOS_Factory (void);
-  // Death and destruction.
 
+  /**
+   * The Event Channel waits until all the children have accepted at
+   * least one event, and then send them all as a single event to the
+   * consumer.
+   */
   int start_conjunction_group (int nchildren = 0);
-  // The Event Channel waits until all the children have accepted at
-  // least one event, and then send them all as a single event to the
-  // consumer.
 
+  /// The consumer accepts any event that is accepted by at least one
+  /// child.
   int start_disjunction_group (int nchildren = 0);
-  // The consumer accepts any event that is accepted by at least one
-  // child.
 
+  /// The consumer only accepts events that pass all the filter
+  /// expressions defined by the children.
   int start_logical_and_group (int nchildren = 0);
-  // The consumer only accepts events that pass all the filter
-  // expressions defined by the children.
 
+  /// The consumer wants all the events *except* the group that
+  /// follows.
   int start_negation (void);
-  // The consumer wants all the events *except* the group that
-  // follows.
 
+  /// Insert a bitmask filter, this acts as a quick rejection mechanism
+  /// for the subsequent filters.
   int start_bitmask (CORBA::ULong source_mask,
                      CORBA::ULong type_mask);
-  // Insert a bitmask filter, this acts as a quick rejection mechanism
-  // for the subsequent filters.
 
+  /**
+   * Inser a new filter that only accepts events with the following
+   * properties:
+   * (event.header.type & type_mask) == type_value
+   * (event.header.source & source_mask) == source_value
+   */
   int insert_bitmasked_value (CORBA::ULong source_mask,
                               CORBA::ULong type_mask,
                               CORBA::ULong source_value,
                               CORBA::ULong type_value);
-  // Inser a new filter that only accepts events with the following
-  // properties:
-  // (event.header.type & type_mask) == type_value
-  // (event.header.source & source_mask) == source_value
 
+  /// Insert a node that accepts any event, useful for bitmask filters.
   int insert_null_terminator (void);
-  // Insert a node that accepts any event, useful for bitmask filters.
 
   // = Insert operations add to the current conjunction or disjunction
   // group.  These return 0 on success, -1 on failure.  Before insert
@@ -162,59 +140,63 @@ public:
   // start_XX_group method is not called, start_conjunction_group is
   // assumed.
 
+  /// Insert the <subscribe> structure describing the event and
+  /// receiving method into the current group.
   int insert (const RtecEventChannelAdmin::Dependency &subscribe);
-  // Insert the <subscribe> structure describing the event and
-  // receiving method into the current group.
 
+  /**
+   * Insert source/type dependency.  <source> of the event (may be
+   * zero), <type> of the event.  <rt_info> describes the method that
+   * will handle the <source>/<type> events.
+   */
   int insert (RtecEventComm::EventSourceID source,
               RtecEventComm::EventType type,
               RtecBase::handle_t rt_info);
-  // Insert source/type dependency.  <source> of the event (may be
-  // zero), <type> of the event.  <rt_info> describes the method that
-  // will handle the <source>/<type> events.
 
+  /// Insert type-only dependency.
   int insert_type (RtecEventComm::EventType type,
                    RtecBase::handle_t rt_info);
-  // Insert type-only dependency.
 
+  /// Insert source-only dependency.
   int insert_source (RtecEventComm::EventSourceID source,
                      RtecBase::handle_t rt_info);
-  // Insert source-only dependency.
 
+  /// Register temporal dependency.  <type> designates interval or
+  /// deadline timeout that will occur every <interval>.
   int insert_time (RtecEventComm::EventType type,
                    RtecEventComm::Time interval,
                    RtecBase::handle_t rt_info);
-  // Register temporal dependency.  <type> designates interval or
-  // deadline timeout that will occur every <interval>.
 
+  /// This will be inserted as type ACE_ES_EVENT_ACT.
   int insert_act (RtecEventComm::EventData act);
-  // This will be inserted as type ACE_ES_EVENT_ACT.
 
   // = Conversion operators.  The Event Channel takes ConsumerQOS
   // objects.
 
+  /// Allows conversions to ConsumerQOS, which is expected by the
+  /// PushSupplierProxy::connect_push_consumer interface.
   const RtecEventChannelAdmin::ConsumerQOS &get_ConsumerQOS (void);
-  // Allows conversions to ConsumerQOS, which is expected by the
-  // PushSupplierProxy::connect_push_consumer interface.
 
+  /// Calls this->get_ConsumerQOS.
   operator const RtecEventChannelAdmin::ConsumerQOS &(void);
-  // Calls this->get_ConsumerQOS.
 
   static void debug (const RtecEventChannelAdmin::ConsumerQOS& qos);
 
 private:
+  /// The representation to be sent to the channel.
   RtecEventChannelAdmin::ConsumerQOS qos_;
-  // The representation to be sent to the channel.
 
+  /// Whether a start_XX_group has been called yet.  This is to make
+  /// sure that a designator is placed in the subscription list first.
   int designator_set_;
-  // Whether a start_XX_group has been called yet.  This is to make
-  // sure that a designator is placed in the subscription list first.
 
+  /**
+   * If not zero this is a user-provided function used to initialize
+   * the events.  When the event contains unions this is required to
+   * avoid marshaling and demarshaling of default initialized unions
+   * that (AFAIK) is not CORBA compliant.
+   */
   TAO_EC_Event_Initializer event_initializer_;
-  // If not zero this is a user-provided function used to initialize
-  // the events.  When the event contains unions this is required to
-  // avoid marshaling and demarshaling of default initialized unions
-  // that (AFAIK) is not CORBA compliant.
 };
 
 // ************************************************************
@@ -222,37 +204,40 @@ private:
 class TAO_RTEvent_Export ACE_SupplierQOS_Factory
 {
 public:
-  // ACE_SupplierQOS_Factory (TAO_EC_Event_Initializer initializer = 0);
+  /// Default construction.
   ACE_SupplierQOS_Factory (TAO_EC_Event_Initializer initializer = 0,
                            int qos_max_len = 0);
-  // Default construction.
 
+  /**
+   * Publish <sid> and <type> that is generate by a method described by
+   * <rtinfo>.  The method generates <type> <ncalls> number of times
+   * per "iteration."
+   */
   int insert (RtecEventComm::EventSourceID sid,
               RtecEventComm::EventType type,
               RtecBase::handle_t rtinfo,
               u_int ncalls);
-  // Publish <sid> and <type> that is generate by a method described by
-  // <rtinfo>.  The method generates <type> <ncalls> number of times
-  // per "iteration."
 
+  /// Allows conversions to SupplierQOS, which is expected by the
+  /// PushSupplierProxy::connect_push_supplier interface.
   const RtecEventChannelAdmin::SupplierQOS &get_SupplierQOS (void);
-  // Allows conversions to SupplierQOS, which is expected by the
-  // PushSupplierProxy::connect_push_supplier interface.
 
+  /// Calls this->get_SupplierQOS.
   operator const RtecEventChannelAdmin::SupplierQOS &(void);
-  // Calls this->get_SupplierQOS.
 
   static void debug (const RtecEventChannelAdmin::SupplierQOS& qos);
 
 private:
+  /// Representation needed by channel.
   RtecEventChannelAdmin::SupplierQOS qos_;
-  // Representation needed by channel.
 
+  /**
+   * If not zero this is a user-provided function used to initialize
+   * the events.  When the event contains unions this is required to
+   * avoid marshaling and demarshaling of default initialized unions
+   * that (AFAIK) is not CORBA compliant.
+   */
   TAO_EC_Event_Initializer event_initializer_;
-  // If not zero this is a user-provided function used to initialize
-  // the events.  When the event contains unions this is required to
-  // avoid marshaling and demarshaling of default initialized unions
-  // that (AFAIK) is not CORBA compliant.
 };