From 229673fc49bb56c3f1207cb82c01f8914850c287 Mon Sep 17 00:00:00 2001 From: Ossama Othman Date: Wed, 10 Apr 2002 17:44:16 +0000 Subject: ChangeLogTag:Wed Apr 10 10:40:36 2002 Ossama Othman --- ace/Bound_Ptr.h | 184 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 111 insertions(+), 73 deletions(-) (limited to 'ace/Bound_Ptr.h') diff --git a/ace/Bound_Ptr.h b/ace/Bound_Ptr.h index 094bdb6b8d2..c1d3d63fc48 100644 --- a/ace/Bound_Ptr.h +++ b/ace/Bound_Ptr.h @@ -1,4 +1,4 @@ -/* -*- C++ -*- */ +// -*- C++ -*- //============================================================================= /** @@ -12,21 +12,25 @@ #ifndef ACE_BOUND_PTR_H #define ACE_BOUND_PTR_H + #include "ace/pre.h" -#include "ace/OS.h" -#include "ace/Auto_Ptr.h" +#include "ace/config-all.h" #if !defined (ACE_LACKS_PRAGMA_ONCE) # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +#include "ace/Auto_Ptr.h" + /** * @class ACE_Bound_Ptr_Counter * - * @brief An ACE_Bound_Ptr_Counter object encapsulates an object - * reference count. Do not use this class directly, use ACE_Strong_Bound_Ptr - * or ACE_Weak_Bound_Ptr instead. + * @brief An ACE_Bound_Ptr_Counter object encapsulates an + * object reference count. + * + * Do not use this class directly, use ACE_Strong_Bound_Ptr or + * ACE_Weak_Bound_Ptr instead. */ template class ACE_Bound_Ptr_Counter @@ -38,40 +42,45 @@ public: ACE_Bound_Ptr_Counter (int init_obj_ref_count = 0); ~ACE_Bound_Ptr_Counter (void); - /// Create a ACE_Bound_Ptr_Counter and initialize the reference - /// count to indicate ownership by a strong pointer. + /// Create a ACE_Bound_Ptr_Counter and initialize the + /// reference count to indicate ownership by a strong pointer. static ACE_Bound_Ptr_Counter *create_strong (void); - /// Increase both the object and counter reference counts and return the new - /// object reference count. A return value of -1 indicates that the object - /// has already been destroyed. + /// Increase both the object and counter reference counts and return + /// the new object reference count. A return value of -1 indicates + /// that the object has already been destroyed. static int attach_strong (ACE_Bound_Ptr_Counter *counter); - /// Decreases both the object and counter reference counts and deletes - /// whichever has no more references. Returns the new object reference count. + /// Decreases both the object and counter reference counts and + /// deletes whichever has no more references. Returns the new object + /// reference count. static int detach_strong (ACE_Bound_Ptr_Counter *counter); - /// Create a ACE_Bound_Ptr_Counter and initialize the reference - /// count to indicate no ownership. + /// Create a ACE_Bound_Ptr_Counter and initialize the + /// reference count to indicate no ownership. static ACE_Bound_Ptr_Counter *create_weak (void); /// Increase the counter reference count and return argument. static void attach_weak (ACE_Bound_Ptr_Counter *counter); - /// Decreases the counter reference count and deletes the counter if it has - /// no more references. + /// Decreases the counter reference count and deletes the counter if + /// it has no more references. static void detach_weak (ACE_Bound_Ptr_Counter *counter); /// Determine whether the object has been deleted. static int object_was_deleted (ACE_Bound_Ptr_Counter *counter); private: - /// Allocate a new ACE_Bound_Ptr_Counter instance, returning NULL - /// if it cannot be created. + + /// Allocate a new ACE_Bound_Ptr_Counter instance, + /// returning NULL if it cannot be created. static ACE_Bound_Ptr_Counter *internal_create (int init_obj_ref_count); - /// Reference count of underlying object. Is set to -1 once the object has - /// been destroyed to indicate to all weak pointers that it is no longer valid. +private: + + /// Reference count of underlying object. Is set to -1 once the + /// object has been destroyed to indicate to all weak pointers that + /// it is no longer valid. int obj_ref_count_; /// Reference count of this counter. @@ -87,7 +96,9 @@ template class ACE_Weak_Bound_Ptr; /** * @class ACE_Strong_Bound_Ptr * - * @brief This class implements support for a reference counted pointer. + * @brief This class implements support for a reference counted + * pointer. + * * Assigning or copying instances of an ACE_Strong_Bound_Ptr will * automatically increment the reference count of the underlying object. * When the last instance of an ACE_Strong_Bound_Ptr that references a @@ -121,19 +132,25 @@ public: /// Assignment operator that binds and to the same object. void operator = (const ACE_Weak_Bound_Ptr &r); - /// Equality operator that returns 1 if both ACE_Strong_Bound_Ptr instances - /// point to the same underlying object. Attention: It also returns 1 if - /// both objects have just been instantiated and not used yet. + /// Equality operator that returns 1 if both ACE_Strong_Bound_Ptr + /// instances point to the same underlying object. + /** + * @note It also returns 1 if both objects have just been + * instantiated and not used yet. + */ int operator == (const ACE_Strong_Bound_Ptr &r) const; /// Equality operator that returns 1 if the ACE_Strong_Bound_Ptr and /// ACE_Weak_Bound_Ptr objects point to the same underlying object. - /// Attention: It also returns 1 if both objects have just been - /// instantiated and not used yet. + /** + * + * @note It also returns 1 if both objects have just been + * instantiated and not used yet. + */ int operator == (const ACE_Weak_Bound_Ptr &r) const; - /// Equality operator that returns 1 if the ACE_Strong_Bound_Ptr and the raw - /// pointer point to the same underlying object. + /// Equality operator that returns 1 if the ACE_Strong_Bound_Ptr and + /// the raw pointer point to the same underlying object. int operator == (X *p) const; /// Inequality operator, which is the opposite of equality. @@ -154,15 +171,17 @@ public: /// Get the pointer value. X *get (void); - /// Resets the ACE_Strong_Bound_Ptr to refer to a different underlying - /// object. + /// Resets the ACE_Strong_Bound_Ptr to refer to a different + /// underlying object. void reset (X *p = 0); - /// Resets the ACE_Strong_Bound_Ptr to refer to a different underlying - /// object, ownership of which is stolen from the auto_ptr. + /// Resets the ACE_Strong_Bound_Ptr to refer to a different + /// underlying object, ownership of which is stolen from the + /// auto_ptr. void reset (auto_ptr p); - /// Allows us to check for NULL on all ACE_Strong_Bound_Ptr objects. + /// Allows us to check for NULL on all ACE_Strong_Bound_Ptr + /// objects. int null (void) const; /// Declare the dynamic allocation hooks. @@ -185,22 +204,24 @@ private: * @class ACE_Weak_Bound_Ptr * * @brief This class implements support for a weak pointer that complements - * ACE_Strong_Bound_Ptr. Unlike ACE_Strong_Bound_Ptr, assigning or copying - * instances of an ACE_Weak_Bound_Ptr will not automatically increment the - * reference count of the underlying object. What ACE_Weak_Bound_Ptr does is - * preserve the knowledge that the object is in fact reference counted, and - * thus provides an alternative to raw pointers where non-ownership - * associations must be maintained. When the last instance of an - * ACE_Strong_Bound_Ptr that references a particular object is destroyed or - * overwritten, the corresponding ACE_Weak_Bound_Ptr instances are set to - * null. + * ACE_Strong_Bound_Ptr. + * + * Unlike ACE_Strong_Bound_Ptr, assigning or copying instances of an + * ACE_Weak_Bound_Ptr will not automatically increment the reference + * count of the underlying object. What ACE_Weak_Bound_Ptr does is + * preserve the knowledge that the object is in fact reference + * counted, and thus provides an alternative to raw pointers where + * non-ownership associations must be maintained. When the last + * instance of an ACE_Strong_Bound_Ptr that references a particular + * object is destroyed or overwritten, the corresponding + * ACE_Weak_Bound_Ptr instances are set to NULL. */ template class ACE_Weak_Bound_Ptr { public: - /// Constructor that initializes an ACE_Weak_Bound_Ptr to point to the - /// object

immediately. + /// Constructor that initializes an ACE_Weak_Bound_Ptr to point to + /// the object

immediately. ACE_EXPLICIT ACE_Weak_Bound_Ptr (X *p = 0); /// Copy constructor binds and to the same object. @@ -218,19 +239,25 @@ public: /// Assignment operator that binds and to the same object. void operator = (const ACE_Strong_Bound_Ptr &r); - /// Equality operator that returns 1 if both ACE_Weak_Bound_Ptr objects - /// point to the same underlying object. Attention: It also returns 1 if - /// both objects have just been instantiated and not used yet. + /// Equality operator that returns 1 if both ACE_Weak_Bound_Ptr + /// objects point to the same underlying object. + /** + * @note It also returns 1 if both objects have just been + * instantiated and not used yet. + */ int operator == (const ACE_Weak_Bound_Ptr &r) const; /// Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and - /// ACE_Strong_Bound_Ptr objects point to the same underlying object. - /// Attention: It also returns 1 if both objects have just been instantiated - /// and not used yet. + /// ACE_Strong_Bound_Ptr objects point to the same underlying + /// object. + /** + * @note It also returns 1 if both objects have just been + * instantiated and not used yet. + */ int operator == (const ACE_Strong_Bound_Ptr &r) const; - /// Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and the raw - /// pointer point to the same underlying object. + /// Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and + /// the raw pointer point to the same underlying object. int operator == (X *p) const; /// Inequality operator, which is the opposite of equality. @@ -242,37 +269,47 @@ public: /// Inequality operator, which is the opposite of equality. int operator != (X *p) const; - /// Redirection operator. It returns a temporary strong pointer and makes - /// use of the chaining properties of operator-> to ensure that the - /// underlying object does not disappear while you are using it. If - /// you are certain of the lifetimes of the object, and do not want to incur - /// the locking overhead, then use the unsafe_get method instead. + /// Redirection operator. + /** + * It returns a temporary strong pointer and makes use of the + * chaining properties of operator-> to ensure that the underlying + * object does not disappear while you are using it. If you are + * certain of the lifetimes of the object, and do not want to incur + * the locking overhead, then use the unsafe_get method instead. + */ ACE_Strong_Bound_Ptr operator-> (void) const; - /// Obtain a strong pointer corresponding to this weak pointer. This function - /// is useful to create a temporary strong pointer for conversion to a - /// reference. + /// Obtain a strong pointer corresponding to this weak pointer. This + /// function is useful to create a temporary strong pointer for + /// conversion to a reference. ACE_Strong_Bound_Ptr strong (void) const; - /// Get the pointer value. Warning: this does not affect the reference count - /// of the underlying object, so it may disappear on you while you are using - /// it if you are not careful. + /// Get the pointer value. Warning: this does not affect the + /// reference count of the underlying object, so it may disappear on + /// you while you are using it if you are not careful. X *unsafe_get (void) const; - /// Resets the ACE_Weak_Bound_Ptr to refer to a different underlying object. + /// Resets the ACE_Weak_Bound_Ptr to refer to a different underlying + /// object. void reset (X *p = 0); - /// Increment the reference count on the underlying object. Returns the new - /// reference count on the object. This function may be used to integrate the - /// bound pointers into an external reference counting mechanism such as - /// those used by COM or CORBA servants. + /// Increment the reference count on the underlying object. + /** + * Returns the new reference count on the object. This function may + * be used to integrate the bound pointers into an external + * reference counting mechanism such as those used by COM or CORBA + * servants. + */ int add_ref (void); /// Decrement the reference count on the underlying object, which is deleted - /// if the count has reached zero. Returns the new reference count on the - /// object. This function may be used to integrate the bound pointers into an - /// external reference counting mechanism such as those used by COM or CORBA - /// servants. + /// if the count has reached zero. + /** + * Returns the new reference count on the object. This function may + * be used to integrate the bound pointers into an external + * reference counting mechanism such as those used by COM or CORBA + * servants. + */ int remove_ref (void); /// Allows us to check for NULL on all ACE_Weak_Bound_Ptr objects. @@ -297,4 +334,5 @@ private: #include "ace/Bound_Ptr.i" #include "ace/post.h" + #endif /* ACE_BOUND_PTR_H */ -- cgit v1.2.1