diff options
Diffstat (limited to 'TAO/tao/Stub.h')
| -rw-r--r-- | TAO/tao/Stub.h | 294 |
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); |