ChangeLogTag:Mon Sep 17 13:18:35 2001 Carlos O'Ryan <coryan@uci.edu>

1 files changed, 125 insertions, 50 deletions

diff --git a/TAO/orbsvcs/orbsvcs/RtecEventComm.idl b/TAO/orbsvcs/orbsvcs/RtecEventComm.idl
index f04ce0e2fc5..b23a71899de 100644
--- a/TAO/orbsvcs/orbsvcs/RtecEventComm.idl
+++ b/TAO/orbsvcs/orbsvcs/RtecEventComm.idl
@@ -1,5 +1,17 @@
-// $Id$
-
+/**
+ * @file RtecEventComm.idl
+ *
+ * @brief Define the RtecEventComm module
+ *
+ * $Id$
+ *
+ * TAO's Real-time Event Service is described in:
+ *
+ * http://doc.ece.uci.edu/~coryan/EC/
+ *
+ * @author Carlos O'Ryan <coryan@uci.edu>
+ * @author Tim Harrison <harrison@cs.wustl.edu>
+ */
 #ifndef TAO_RTEC_EVENTCOMM_IDL
 #define TAO_RTEC_EVENTCOMM_IDL
 
@@ -12,89 +24,152 @@
 
 #include "RtecDefaultEventData.idl"
 
+/**
+ * @namespace RtecEventComm
+ *
+ * @brief Interfaces and data structures used by the event service
+ *   clients
+ */
 module RtecEventComm
 {
-  // = TITLE
-  //   User defined Event Data.
-  //
-  // = DESCRIPTION
-  //   The Event payload is defined by this type.
-  //   Users wanting maximum flexibility can use an Any,
-  //   users that only have one type of event may use structures,
-  //   other users may preffer union, trying to strike a balance
-  //   between performance and flexibility.
-  //   Users willing to implement their own marshalling may use a
-  //   sequence of octet.
-
+  /// The event data
   typedef RtecEventData EventData;
 
+  /// Shortcut for the time structures.
   typedef TimeBase::TimeT Time;
 
   typedef long EventSourceID;
   typedef long EventType;
 
+  /**
+   * @struct EventHeader
+   *
+   * @brief Define the structure of an event header
+   *
+   * The event header is the portion of the event examined by the
+   * event service for filtering purposes.
+   *
+   * Events can be filtered based on their type and SourceID, though
+   * the latest is a misnomer, over time it has evolved into a 'source
+   * class' or 'event domain' field, i.e. multiple sources can have
+   * the same 'ID' and the same source can generate events with
+   * different IDs.
+   */
   struct EventHeader
   {
-    // = TITLE
-    //   The Event Header
-    //
-    // = DESCRIPTION
-    //   Each event carries some information to do filtering,
-    //   correlation, etc.
+    /// The event type.
+    /**
+     * Notice that the 'type' of the event may or may not be related
+     * to the data type in its contents.  I.e. it is perfectly
+     * possible to send the same payload with different values in this
+     * field.  In other words, this is just a filterable value, and
+     * it is up to the application to define (or not) its relation to
+     * the contents of the event.
+     */
     EventType type;
-    // The event type.
-    // This may be different from the discriminator in the EventData
-    // union above, the motivation is to allow filtering by data
-    // contents: different event types are assigned to different data
-    // contents though they use the same discriminator.
 
+    /// Some way to identify the supplier.
     EventSourceID source;
-    // Some way to identify the supplier.
 
+    /// The "Time To Live" counter.
+    /**
+     * Each time an EC process the event it decreases the TTL field,
+     * when it gets to zero the message is no longer forwarded.
+     */
     long ttl;
-    // The "Time To Live" count, each time an EC process the event it
-    // decreases the TTL field, when it gets to zero the message is no
-    // longer forwarded.
 
+    /// Applications can use this field to time-stamp the event at the
+    /// source.
+    /**
+     * @todo Because the filtering language uses EventHeaders as
+     * filtering expressions (yeah, it sucks) we also use this field
+     * to pass timeout values into the EC filter.
+     */
     Time creation_time;
-    // A time value, the name is a bit misleading, it is used for
-    // timestamping but also used to setup timers in the consumer
-    // subscriptions.
+
 #ifndef TAO_LACKS_EVENT_CHANNEL_TIMESTAMPS
+    //@{
+    /** @name Benchmarking timestamps
+     *
+     * The following timestamps are used to benchmark the Event
+     * Channel, they should not be used by the application and may be
+     * removed without notice.
+     */
     Time ec_recv_time;
     Time ec_send_time;
-    // Some timestamps, they actually belong in the payload, for some
-    // kind of measument event.
+    //@}
 #endif /* TAO_LACKS_EVENT_CHANNEL_TIMESTAMPS */
   };
 
+  /**
+   * @struct Event
+   *
+   * @brief The basic events delivered by the Event Service.
+   *
+   * The event service uses this structure to pass events around.
+   */
   struct Event
   {
-    // = TITLE
-    //   The Event structure.
-    //
-    // = DESCRIPTION
-    //   Events are represented by this structure, it is simply a
-    //   header,data pair.
-    //
+    /// The header, used for filtering
     EventHeader header;
 
+    /// The payload, the event service treats this as an opaque data
+    /// field.
     EventData data;
-    // The event payload.
   };
+  /// The real argument to the push() operations.
+  /**
+   * For performance reasons TAO's Real-time Event Service uses
+   * sequences of events
+   */
   typedef sequence<Event> EventSet;
 
+  /**
+   * @interface PushConsumer
+   *
+   * @brief Define the interface used by consumers to receive events.
+   *
+   * Applications usually implement this interface to subscribe for
+   * events.
+   */
   interface PushConsumer
-    {
-      oneway void push (in EventSet data);
-      void disconnect_push_consumer ();
-    };
+  {
+    /// Main event delivery callback
+    oneway void push (in EventSet data);
+
+    /// Callback method to indicate a disconnection.
+    /**
+     * If the event service is destroyed while a consumer is still
+     * connected then the following callback operation is invoked on
+     * the consumer.
+     *
+     * The same operation is used by suppliers to disconnect from the
+     * Event Channel, but it is invoked via their
+     * RtecEventChannelAdmin::ProxyPushConsumer peer.
+     */
+    void disconnect_push_consumer ();
+  };
 
+  /**
+   * @interface PushSupplier
+   *
+   * @brief Defines the interface used by suppliers to receive
+   *        callbacks from the Event Channel.
+   */
   interface PushSupplier
-    {
-      void disconnect_push_supplier ();
-    };
-
+  {
+    /// Callback method to indicate a disconnection.
+    /**
+     * If the event service is destroyed while a supplier is still
+     * connected then the following callback operation is invoked on
+     * the supplier.
+     *
+     * The same operation is used by consumers to disconnect from the
+     * Event Channel, but it is invoked via their
+     * RtecEventChannelAdmin::ProxyPushSupplier peer.
+     */
+    void disconnect_push_supplier ();
+  };
 };
 
 #endif /* TAO_RTEC_EVENTCOMM_IDL */