ChangeLogTag:Fri Dec 15 11:36:08 2000 Carlos O'Ryan <coryan@uci.edu>

1 files changed, 156 insertions, 138 deletions

diff --git a/TAO/tao/Stub.h b/TAO/tao/Stub.h
index 31bc070b8ce..d15ca555f3e 100644
--- a/TAO/tao/Stub.h
+++ b/TAO/tao/Stub.h
@@ -1,33 +1,30 @@
 // This may look like C, but it's really -*- C++ -*-
 
-// $Id$
-
-// ============================================================================
-//
-// = LIBRARY
-//    TAO
-//
-// = FILENAME
-//    Stub.h
-//
-// = DESCRIPTION
-//
-//    Data structures used by static and dynamic stubs, and to a
-//    lesser degree by skeletons
-//
-//    Header file for Win32 C/C++/COM interface to one kind of CORBA
-//    remote invocation framework.  This is for use by
-//    compiler-generated code, not by portable applications!
-//
-//    These constitute the stub API to this "ORB Core."  Such
-//    interfaces are not specified by OMG, and may differ between
-//    different ORBs.  This one has the particular advantage that
-//    stubs can be quite small.
-//
-// = AUTHOR
-//     Copyright 1994-1995 by Sun Microsystems, Inc.
-//
-// ============================================================================
+
+//=============================================================================
+/**
+ *  @file    Stub.h
+ *
+ *  $Id$
+ *
+ *
+ *  Data structures used by static and dynamic stubs, and to a
+ *  lesser degree by skeletons
+ *
+ *  Header file for Win32 C/C++/COM interface to one kind of CORBA
+ *  remote invocation framework.  This is for use by
+ *  compiler-generated code, not by portable applications!
+ *
+ *  These constitute the stub API to this "ORB Core."  Such
+ *  interfaces are not specified by OMG, and may differ between
+ *  different ORBs.  This one has the particular advantage that
+ *  stubs can be quite small.
+ *
+ *
+ *  @author  Copyright 1994-1995 by Sun Microsystems, Inc.
+ */
+//=============================================================================
+
 
 #ifndef TAO_STUB_H
 #define TAO_STUB_H
@@ -92,33 +89,35 @@ struct TAO_Exception_Data
   // The allocator for this exception.
 };
 
+/**
+ * @class TAO_Stub
+ *
+ * @brief TAO_Stub
+ *
+ * Per-objref data includes the (protocol-specific) Profile, which
+ * is handled by placing it into a subclass of this type along
+ * with data that may be used in protocol-specific caching
+ * schemes.
+ * The type ID (the data specified by CORBA 2.0 that gets exposed
+ * "on the wire", and in stringified objrefs) is held by this
+ * module.
+ * The stub APIs are member functions of this
+ * type.
+ */
 class TAO_Export TAO_Stub
 {
-  // = TITLE
-  //    TAO_Stub
-  //
-  // = DESCRIPTION
-  //    Per-objref data includes the (protocol-specific) Profile, which
-  //    is handled by placing it into a subclass of this type along
-  //    with data that may be used in protocol-specific caching
-  //    schemes.
-  //
-  //    The type ID (the data specified by CORBA 2.0 that gets exposed
-  //    "on the wire", and in stringified objrefs) is held by this
-  //    module.
-  //
-  //    The stub APIs are member functions of this
-  //    type.
 public:
 #if (TAO_HAS_CORBA_MESSAGING == 1)
 
+  /**
+   * Returns the effective policy if <type> is a known client-exposed
+   * policy type.  Returns the effective override for all other policy
+   * types.
+   */
   CORBA::Policy_ptr get_policy (CORBA::PolicyType type,
                                 CORBA::Environment &ACE_TRY_ENV =
                                 TAO_default_environment ()
     );
-  // Returns the effective policy if <type> is a known client-exposed
-  // policy type.  Returns the effective override for all other policy
-  // types.
 
   CORBA::Policy_ptr get_client_policy (CORBA::PolicyType type,
                                        CORBA::Environment &ACE_TRY_ENV =
@@ -143,17 +142,17 @@ public:
 
 #if (TAO_HAS_RT_CORBA == 1)
 
+  /// Returns the RTCORBA::PriorityModelPolicy exported
+  /// in object's IOR.
   TAO_PriorityModelPolicy *exposed_priority_model (void);
-  // Returns the RTCORBA::PriorityModelPolicy exported
-  // in object's IOR.
 
+  /// Returns the RTCORBA::PriorityBandedConnectionPolicy exported
+  /// in object's IOR.
   TAO_PriorityBandedConnectionPolicy *exposed_priority_banded_connection (void);
-  // Returns the RTCORBA::PriorityBandedConnectionPolicy exported
-  // in object's IOR.
 
+  /// Returns the RTCORBA::ClientProtocolPolicy exported
+  /// in object's IOR.
   TAO_ClientProtocolPolicy *exposed_client_protocol (void);
-  // Returns the RTCORBA::ClientProtocolPolicy exported
-  // in object's IOR.
 
 # endif /*TAO_HAS_RT_CORBA == 1*/
 
@@ -208,151 +207,165 @@ public:
 
 #endif /* TAO_HAS_RT_CORBA == 1 */
 
+  /// Return the sync strategy to be used in by the transport.
+  /// Selection will be based on the SyncScope policies.
   TAO_Sync_Strategy &sync_strategy (void);
-  // Return the sync strategy to be used in by the transport.
-  // Selection will be based on the SyncScope policies.
 
+  /// All objref representations carry around a type ID.
   CORBA::String_var type_id;
-  // All objref representations carry around a type ID.
 
+  /**
+   * All objref representations know how to hash themselves and
+   * compare themselves for equivalence to others.  It's easily
+   * possible to have two objrefs that are distinct copies of data
+   * that refers/points to the same remote object (i.e. are
+   * equivalent).
+   */
   CORBA::ULong hash (CORBA::ULong maximum,
           CORBA_Environment &ACE_TRY_ENV = TAO_default_environment ());
-  // All objref representations know how to hash themselves and
-  // compare themselves for equivalence to others.  It's easily
-  // possible to have two objrefs that are distinct copies of data
-  // that refers/points to the same remote object (i.e. are
-  // equivalent).
 
+  /// Implement the is_equivalent() method for the CORBA::Object
   CORBA::Boolean is_equivalent (CORBA::Object_ptr other_obj);
-  // Implement the is_equivalent() method for the CORBA::Object
 
   // Our Constructors ...
 
+  /// Construct from a repository ID and a list of profiles.
   TAO_Stub (const char *repository_id,
             const TAO_MProfile &profiles,
             TAO_ORB_Core *orb_core);
-  // Construct from a repository ID and a list of profiles.
 
   // = Memory management.
   CORBA::ULong _incr_refcnt (void);
   CORBA::ULong _decr_refcnt (void);
 
   // Manage the base (non-forwarded) profiles.
+  /// returns a pointer to the profile_in_use object.  This object
+  /// retains ownership of this profile.
   TAO_Profile *profile_in_use (void) ;
-  // returns a pointer to the profile_in_use object.  This object
-  // retains ownership of this profile.
 
+  /**
+   * Copy of the profile list, user must free memory when done.
+   * although the user can call make_profiles() then reorder
+   * the list and give it back to TAO_Stub.
+   */
   TAO_MProfile *make_profiles (void);
-  // Copy of the profile list, user must free memory when done.
-  // although the user can call make_profiles() then reorder
-  // the list and give it back to TAO_Stub.
 
+  /// Obtain a reference to the basic profile set.
   const TAO_MProfile& base_profiles (void) const;
-  // Obtain a reference to the basic profile set.
 
+  /// Obtain a reference to the basic profile set.
   TAO_MProfile& base_profiles (void);
-  // Obtain a reference to the basic profile set.
 
   // Manage forward and base profiles.
+  /**
+   * THREAD SAFE.  If forward_profiles is null then this will
+   * get the next profile in the base_profiles list.  If forward is not null
+   * then this will get the next profile for the list of forwarding
+   * profiles.  If all profiles have been tried then 0 is returned and
+   * profile_in_use_ is set to the first profile in the base_profiles
+   * list.
+   */
   TAO_Profile *next_profile (void);
-  // THREAD SAFE.  If forward_profiles is null then this will
-  // get the next profile in the base_profiles list.  If forward is not null
-  // then this will get the next profile for the list of forwarding
-  // profiles.  If all profiles have been tried then 0 is returned and
-  // profile_in_use_ is set to the first profile in the base_profiles
-  // list.
 
+  /// NON-THREAD SAFE version of next_profile (void)
   TAO_Profile *next_profile_i (void);
-  // NON-THREAD SAFE version of next_profile (void)
 
+  /**
+   * THREAD SAFE
+   * this method will reset the base profile list to reference the first
+   * profile and if there are anmy existing forward profiles they are
+   * reset.
+   */
   void reset_profiles (void);
-  // THREAD SAFE
-  // this method will reset the base profile list to reference the first
-  // profile and if there are anmy existing forward profiles they are
-  // reset.
 
+  /// NON-THREAD SAFE version of reset_profiles (void);
   void reset_profiles_i (void);
-  // NON-THREAD SAFE version of reset_profiles (void);
 
+  /// Returns 1 if a forward profile has successfully been used.
+  /// profile_success_ && forward_profiles_
   CORBA::Boolean valid_forward_profile (void);
-  // Returns 1 if a forward profile has successfully been used.
-  // profile_success_ && forward_profiles_
 
+  /// NON-THREAD-SAFE.  Will set profile_success_ to 0.
   void set_valid_profile (void);
-  // NON-THREAD-SAFE.  Will set profile_success_ to 0.
 
+  /// Returns TRUE if a connection was successful with at least
+  /// one profile.
   CORBA::Boolean valid_profile (void);
-  // Returns TRUE if a connection was successful with at least
-  // one profile.
 
+  /// Initialize the base_profiles_ and set profile_in_use_ to
+  /// reference the first profile.
   TAO_Profile *base_profiles (const TAO_MProfile& mprofiles);
-  // Initialize the base_profiles_ and set profile_in_use_ to
-  // reference the first profile.
 
+  /**
+   * THREAD SAFE.
+   * Set the forward_profiles.  This object will assume ownership of
+   * this TAO_MProfile object!!
+   */
   void add_forward_profiles (const TAO_MProfile &mprofiles);
-  // THREAD SAFE.
-  // Set the forward_profiles.  This object will assume ownership of
-  // this TAO_MProfile object!!
 
+  /**
+   * THREAD SAFE
+   * Used to get the next profile after the one being used has
+   * failed during the initial connect or send of the message!
+   */
   CORBA::Boolean next_profile_retry (void);
-  // THREAD SAFE
-  // Used to get the next profile after the one being used has
-  // failed during the initial connect or send of the message!
 
+  /// Accessor.
   TAO_ORB_Core* orb_core (void) const;
-  // Accessor.
 
+  /// This returns a duplicated ORB pointer.
   CORBA::ORB_ptr servant_orb_ptr (void);
-  // This returns a duplicated ORB pointer.
 
+  /// This returns the ORB var itself (generally for temporary use).
   CORBA::ORB_var &servant_orb_var (void);
-  // This returns the ORB var itself (generally for temporary use).
 
+  /**
+   * Accesor and mutator for the servant ORB.  Notice that the muatator
+   * assumes the ownership of the passed in ORB and the accesor does not
+   * return a copy of the orb since the accessing of the ORB is considered
+   * temporary.
+   */
   void servant_orb (CORBA::ORB_ptr orb);
-  // Accesor and mutator for the servant ORB.  Notice that the muatator
-  // assumes the ownership of the passed in ORB and the accesor does not
-  // return a copy of the orb since the accessing of the ORB is considered
-  // temporary.
 
+  /// Set the addressing mode.
   void addressing_mode (CORBA::Short addr_mode);
-  // Set the addressing mode.
 
+  /// Return the Addressing mode.
   CORBA::Short addressing_mode (void);
-  // Return the Addressing mode.
 
+  /// Make a call on to services to see whether they have some
+  /// preferences on selecting the right profiles.
   CORBA::Boolean service_profile_selection (void);
-  // Make a call on to services to see whether they have some
-  // preferences on selecting the right profiles.
 
 private:
+  /// Makes a copy of the profile and frees the existing profile_in_use.
+  /// NOT THREAD SAFE
   TAO_Profile *set_profile_in_use_i (TAO_Profile *pfile);
-  // Makes a copy of the profile and frees the existing profile_in_use.
-  // NOT THREAD SAFE
 
+  /// NON-THREAD-SAFE.  Utility method which resets or initializes
+  /// the base_profile list and forward flags.
   void reset_base ();
-  // NON-THREAD-SAFE.  Utility method which resets or initializes
-  // the base_profile list and forward flags.
 
+  /// NON-THREAD-SAFE.  Utility method which unrolls (removes or pops)
+  /// the top most forwarding profile list.
   void forward_back_one (void);
-  // NON-THREAD-SAFE.  Utility method which unrolls (removes or pops)
-  // the top most forwarding profile list.
 
+   /// NOT THREAD-SAFE.  Utility method which pops all forward profile
+   /// lists and resets the forward_profiles_ pointer.
   void reset_forward ();
-   // NOT THREAD-SAFE.  Utility method which pops all forward profile
-   // lists and resets the forward_profiles_ pointer.
 
+  /// Destructor is to be called only through _decr_refcnt().
   ~TAO_Stub (void);
-  // Destructor is to be called only through _decr_refcnt().
 
+  /// NON-THREAD-SAFE.  utility method for next_profile.
   TAO_Profile *next_forward_profile (void);
-  // NON-THREAD-SAFE.  utility method for next_profile.
 
 #if (TAO_HAS_RT_CORBA == 1)
 
 private:
 
+  /// Helper method used to parse the policies.
   void parse_policies (void);
-  // Helper method used to parse the policies.
 
   void exposed_priority_model (CORBA::Policy_ptr policy);
 
@@ -378,48 +391,50 @@ private:
 #endif /* TAO_HAS_RT_CORBA == 1 */
 private:
 
+  /// Ordered list of profiles for this object.
   TAO_MProfile base_profiles_;
-  // Ordered list of profiles for this object.
 
+  /// The list of forwarding profiles.  This is actually implemented as a
+  /// linked list of TAO_MProfile objects.
   TAO_MProfile *forward_profiles_;
-  // The list of forwarding profiles.  This is actually implemented as a
-  // linked list of TAO_MProfile objects.
 
+  /// This is the profile that we are currently sending/receiving with.
   TAO_Profile *profile_in_use_;
-  // This is the profile that we are currently sending/receiving with.
 
+  /// Mutex to protect access to the forwarding profile.
   ACE_Lock* profile_lock_ptr_;
-  // Mutex to protect access to the forwarding profile.
 
+  /// Have we successfully talked to the forward profile yet?
   size_t profile_success_;
-  // Have we successfully talked to the forward profile yet?
 
+  /// Mutex to protect reference count.
   ACE_SYNCH_MUTEX refcount_lock_;
-  // Mutex to protect reference count.
 
+  /// Number of outstanding references to this object.
   CORBA::ULong refcount_;
-  // Number of outstanding references to this object.
 
+  /// The ORB.
   TAO_ORB_Core* orb_core_;
-  // The ORB.
 
+  /// ORB required for reference counting.  This will help us keep the
+  /// ORB around until the CORBA::Object we represent dies.
   CORBA::ORB_var orb_;
-  // ORB required for reference counting.  This will help us keep the
-  // ORB around until the CORBA::Object we represent dies.
 
+  /**
+   * If this stub refers to a collocated object then we need to hold on to
+   * the servant's ORB (which may be different from the client ORB) so that,
+   *   1. we know that the ORB will stay alive long enough, and,
+   *   2. we can search for the servant/POA's status starting from
+   *      the ORB's RootPOA.
+   */
   CORBA::ORB_var servant_orb_;
-  // If this stub refers to a collocated object then we need to hold on to
-  // the servant's ORB (which may be different from the client ORB) so that,
-  //   1. we know that the ORB will stay alive long enough, and,
-  //   2. we can search for the servant/POA's status starting from
-  //      the ORB's RootPOA.
 
+  /// The policy overrides in this object, if nil then use the default
+  /// policies.
   TAO_Policy_Manager_Impl *policies_;
-  // The policy overrides in this object, if nil then use the default
-  // policies.
 
+  /// The addressing mode.
   CORBA::Short addressing_mode_;
-  // The addressing mode.
 
   // = Disallow copy constructor and assignment operator.
   ACE_UNIMPLEMENTED_FUNC (TAO_Stub (const TAO_Stub &))
@@ -433,11 +448,14 @@ private:
 };
 
 // Define a TAO_Stub auto_ptr class.
+/**
+ * @class TAO_Stub_Auto_Ptr
+ *
+ * @brief Implements the draft C++ standard auto_ptr abstraction.
+ * This class allows one to work Stub Objects *Only*!
+ */
 class TAO_Export TAO_Stub_Auto_Ptr
 {
-  // = TITLE
-  //     Implements the draft C++ standard auto_ptr abstraction.
-  //     This class allows one to work Stub Objects *Only*!
 public:
   // = Initialization and termination methods.
   /* explicit */ TAO_Stub_Auto_Ptr (TAO_Stub *p = 0);