Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

ACE_Weak_Bound_Ptr Class Template Reference

This class implements support for a weak pointer that complements ACE_Strong_Bound_Ptr. More...

#include <Bound_Ptr.h>

Collaboration diagram for ACE_Weak_Bound_Ptr:

Collaboration graph
[legend]
List of all members.

Public Methods

ACE_EXPLICIT ACE_Weak_Bound_Ptr (X *p=0)
 Constructor that initializes an ACE_Weak_Bound_Ptr to point to the object <p> immediately. More...

 ACE_Weak_Bound_Ptr (const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &r)
 Copy constructor binds <this> and <r> to the same object. More...

 ACE_Weak_Bound_Ptr (const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &r)
 Constructor binds <this> and <r> to the same object. More...

 ~ACE_Weak_Bound_Ptr (void)
 Destructor. More...

void operator= (const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &r)
 Assignment operator that binds <this> and <r> to the same object. More...

void operator= (const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &r)
 Assignment operator that binds <this> and <r> to the same object. More...

int operator== (const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &r) const
 Equality operator that returns 1 if both ACE_Weak_Bound_Ptr objects point to the same underlying object. More...

int operator== (const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &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. More...

int operator== (X *p) const
 Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and the raw pointer point to the same underlying object. More...

int operator!= (const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &r) const
 Inequality operator, which is the opposite of equality. More...

int operator!= (const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &r) const
 Inequality operator, which is the opposite of equality. More...

int operator!= (X *p) const
 Inequality operator, which is the opposite of equality. More...

ACE_Strong_Bound_Ptr< X, ACE_LOCK > operator-> (void) const
 Redirection operator. More...

ACE_Strong_Bound_Ptr< X, ACE_LOCK > strong (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. More...

X * unsafe_get (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. More...

void reset (X *p=0)
 Resets the ACE_Weak_Bound_Ptr to refer to a different underlying object. More...

int add_ref (void)
 Increment the reference count on the underlying object. More...

int remove_ref (void)
 Decrement the reference count on the underlying object, which is deleted if the count has reached zero. More...

int null (void) const
 Allows us to check for NULL on all ACE_Weak_Bound_Ptr objects. More...


Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...


Private Types

typedef ACE_Bound_Ptr_Counter<
ACE_LOCK > 		COUNTER
 The ACE_Bound_Ptr_Counter type. More...


Private Attributes

COUNTER * counter_
 The reference counter. More...

X * ptr_
 The underlying object. More...


Friends

class ACE_Strong_Bound_Ptr< X, ACE_LOCK >

Detailed Description

template<class X, class ACE_LOCK>
class ACE_Weak_Bound_Ptr< X, ACE_LOCK >

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.

Definition at line 220 of file Bound_Ptr.h.

Member Typedef Documentation

template<class X, class ACE_LOCK>
typedef ACE_Bound_Ptr_Counter<ACE_LOCK> ACE_Weak_Bound_Ptr::COUNTER [private]
 

The ACE_Bound_Ptr_Counter type.

Definition at line 325 of file Bound_Ptr.h.

Constructor & Destructor Documentation

template<class X, class ACE_LOCK>
ACE_Weak_Bound_Ptr< X, ACE_LOCK >::ACE_Weak_Bound_Ptr (  X *    p = 0 )  [inline]
 

Constructor that initializes an ACE_Weak_Bound_Ptr to point to the object <p> immediately.

Definition at line 309 of file Bound_Ptr.i. 

00310   : counter_ (COUNTER::create_weak ()),
00311     ptr_ (p)
00312 {
00313 }

template<class X, class ACE_LOCK>
ACE_Weak_Bound_Ptr< X, ACE_LOCK >::ACE_Weak_Bound_Ptr (  const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &    r )  [inline]
 

Copy constructor binds <this> and <r> to the same object.

Definition at line 316 of file Bound_Ptr.i. 

00317   : counter_ (r.counter_),
00318     ptr_ (r.ptr_)
00319 {
00320   COUNTER::attach_weak (this->counter_);
00321 }

template<class X, class ACE_LOCK>
ACE_Weak_Bound_Ptr< X, ACE_LOCK >::ACE_Weak_Bound_Ptr (  const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &    r )  [inline]
 

Constructor binds <this> and <r> to the same object.

Definition at line 324 of file Bound_Ptr.i. 

00325   : counter_ (r.counter_),
00326     ptr_ (r.ptr_)
00327 {
00328   COUNTER::attach_weak (this->counter_);
00329 }

template<class X, class ACE_LOCK>
ACE_Weak_Bound_Ptr< X, ACE_LOCK >::~ACE_Weak_Bound_Ptr (  void    )  [inline]
 

Destructor.

Definition at line 332 of file Bound_Ptr.i. 

00333 {
00334   COUNTER::detach_weak (this->counter_);
00335 }

Member Function Documentation

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::add_ref (  void    )  [inline]
 

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.

Definition at line 466 of file Bound_Ptr.i.

References counter_. 

00467 {
00468   return COUNTER::attach_strong (counter_);
00469 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::null (  void    )  const [inline]
 

Allows us to check for NULL on all ACE_Weak_Bound_Ptr objects.

Definition at line 446 of file Bound_Ptr.i.

References ptr_. 

00447 {
00448   // A weak pointer must behave as though it is automatically set to null
00449   // if the underlying object has been deleted.
00450   if (COUNTER::object_was_deleted (this->counter_))
00451     return 1;
00452 
00453   return this->ptr_ == 0;
00454 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator!= (  X *    p )  const [inline]
 

Inequality operator, which is the opposite of equality.

Definition at line 415 of file Bound_Ptr.i.

References ptr_. 

00416 {
00417   // A weak pointer must behave as though it is automatically set to null
00418   // if the underlying object has been deleted.
00419   if (COUNTER::object_was_deleted (this->counter_))
00420     return p != 0;
00421 
00422   return this->ptr_ != p;
00423 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator!= (  const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &    r )  const [inline]
 

Inequality operator, which is the opposite of equality.

Definition at line 404 of file Bound_Ptr.i.

References ptr_, and ACE_Strong_Bound_Ptr::ptr_. 

00405 {
00406   // A weak pointer must behave as though it is automatically set to null
00407   // if the underlying object has been deleted.
00408   if (COUNTER::object_was_deleted (this->counter_))
00409     return r.ptr_ != 0;
00410 
00411   return this->ptr_ != r.ptr_;
00412 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator!= (  const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &    r )  const [inline]
 

Inequality operator, which is the opposite of equality.

Definition at line 393 of file Bound_Ptr.i.

References ptr_. 

00394 {
00395   // A weak pointer must behave as though it is automatically set to null
00396   // if the underlying object has been deleted.
00397   if (COUNTER::object_was_deleted (this->counter_))
00398     return r.ptr_ != 0;
00399 
00400   return this->ptr_ != r.ptr_;
00401 }

template<class X, class ACE_LOCK>
ACE_Strong_Bound_Ptr< X, ACE_LOCK > ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator-> (  void    )  const [inline]
 

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.

Definition at line 426 of file Bound_Ptr.i. 

00427 {
00428   return ACE_Strong_Bound_Ptr<X, ACE_LOCK> (*this);
00429 }

template<class X, class ACE_LOCK>
void ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator= (  const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &    r )  [inline]
 

Assignment operator that binds <this> and <r> to the same object.

Definition at line 349 of file Bound_Ptr.i.

References counter_, ACE_Strong_Bound_Ptr::counter_, ACE_Strong_Bound_Ptr::ptr_, and ptr_. 

00350 {
00351   // This will work if &rhs == this, by first increasing the ref count
00352   COUNTER *new_counter = rhs.counter_;
00353   COUNTER::attach_weak (new_counter);
00354   COUNTER::detach_weak (this->counter_);
00355   this->counter_ = new_counter;
00356   this->ptr_ = rhs.ptr_;
00357 }

template<class X, class ACE_LOCK>
void ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator= (  const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &    r )  [inline]
 

Assignment operator that binds <this> and <r> to the same object.

Definition at line 338 of file Bound_Ptr.i.

References counter_, and ptr_. 

00339 {
00340   // This will work if &rhs == this, by first increasing the ref count
00341   COUNTER *new_counter = rhs.counter_;
00342   COUNTER::attach_weak (new_counter);
00343   COUNTER::detach_weak (this->counter_);
00344   this->counter_ = new_counter;
00345   this->ptr_ = rhs.ptr_;
00346 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator== (  X *    p )  const [inline]
 

Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and the raw pointer point to the same underlying object.

Definition at line 382 of file Bound_Ptr.i.

References ptr_. 

00383 {
00384   // A weak pointer must behave as though it is automatically set to null
00385   // if the underlying object has been deleted.
00386   if (COUNTER::object_was_deleted (this->counter_))
00387     return p == 0;
00388 
00389   return this->ptr_ == p;
00390 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator== (  const ACE_Strong_Bound_Ptr< X, ACE_LOCK > &    r )  const [inline]
 

Equality operator that returns 1 if the ACE_Weak_Bound_Ptr and 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.

Definition at line 371 of file Bound_Ptr.i.

References ptr_, and ACE_Strong_Bound_Ptr::ptr_. 

00372 {
00373   // A weak pointer must behave as though it is automatically set to null
00374   // if the underlying object has been deleted.
00375   if (COUNTER::object_was_deleted (this->counter_))
00376     return r.ptr_ == 0;
00377 
00378   return this->ptr_ == r.ptr_;
00379 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::operator== (  const ACE_Weak_Bound_Ptr< X, ACE_LOCK > &    r )  const [inline]
 

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.

Definition at line 360 of file Bound_Ptr.i.

References ptr_. 

00361 {
00362   // A weak pointer must behave as though it is automatically set to null
00363   // if the underlying object has been deleted.
00364   if (COUNTER::object_was_deleted (this->counter_))
00365     return r.ptr_ == 0;
00366 
00367   return this->ptr_ == r.ptr_;
00368 }

template<class X, class ACE_LOCK>
int ACE_Weak_Bound_Ptr< X, ACE_LOCK >::remove_ref (  void    )  [inline]
 

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.

Definition at line 472 of file Bound_Ptr.i.

References counter_, and ptr_. 

00473 {
00474   int new_obj_ref_count = COUNTER::detach_strong (counter_);
00475   if (new_obj_ref_count == 0)
00476     {
00477       delete this->ptr_;
00478       this->ptr_ = 0;
00479     }
00480   return new_obj_ref_count;
00481 }

template<class X, class ACE_LOCK>
void ACE_Weak_Bound_Ptr< X, ACE_LOCK >::reset (  X *    p = 0 )  [inline]
 

Resets the ACE_Weak_Bound_Ptr to refer to a different underlying object.

Definition at line 457 of file Bound_Ptr.i.

References counter_, and ptr_. 

00458 {
00459   COUNTER *old_counter = this->counter_;
00460   this->counter_ = COUNTER::create_weak ();
00461   this->ptr_ = p;
00462   COUNTER::detach_weak (old_counter);
00463 }

template<class X, class ACE_LOCK>
ACE_Strong_Bound_Ptr< X, ACE_LOCK > ACE_Weak_Bound_Ptr< X, ACE_LOCK >::strong (  void    )  const [inline]
 

Obtain a strong pointer corresponding to this weak pointer. This function is useful to create a temporary strong pointer for conversion to a reference.

Definition at line 432 of file Bound_Ptr.i. 

00433 {
00434   return ACE_Strong_Bound_Ptr<X, ACE_LOCK> (*this);
00435 }

template<class X, class ACE_LOCK>
X * ACE_Weak_Bound_Ptr< X, ACE_LOCK >::unsafe_get (  void    )  const [inline]
 

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.

Definition at line 438 of file Bound_Ptr.i.

References ptr_. 

00439 {
00440   // We do not check if the object has been deleted, since this operation
00441   // is defined to be unsafe!
00442   return this->ptr_;
00443 }

Friends And Related Function Documentation

template<class X, class ACE_LOCK>
friend class ACE_Strong_Bound_Ptr< X, ACE_LOCK > [friend]
 

Definition at line 322 of file Bound_Ptr.h.

Member Data Documentation

template<class X, class ACE_LOCK>
ACE_Weak_Bound_Ptr::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

Definition at line 319 of file Bound_Ptr.h.

template<class X, class ACE_LOCK>
COUNTER* ACE_Weak_Bound_Ptr::counter_ [private]
 

The reference counter.

Definition at line 328 of file Bound_Ptr.h.

Referenced by add_ref, operator=, ACE_Strong_Bound_Ptr::operator=, remove_ref, and reset.

template<class X, class ACE_LOCK>
X* ACE_Weak_Bound_Ptr::ptr_ [private]
 

The underlying object.

Definition at line 331 of file Bound_Ptr.h.

Referenced by null, operator!=, operator=, ACE_Strong_Bound_Ptr::operator=, operator==, remove_ref, reset, and unsafe_get.

The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:59:08 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002