lkptr - simple reference LinKed PoinTeR:
Public Member Functions | Private Member Functions | Private Attributes | Friends
base_lkptr< X > Class Template Reference

Accesory class that contains the fields all lkptr<> intelligent pointers. More...

#include <lkptr.h>

List of all members.

Public Member Functions

X * get () const throw ()
 Returns a pointer to referenced object.
X & value () const throw ()
 Returns the referenced object.
X & operator* () const throw ()
 Returns the referenced object.
X * operator-> () const throw ()
 Returns a pointer to referenced object.
bool isNull () const throw ()
 Returns true if the object pointed is null and false otherwise.
bool unique () const throw ()
 Return "true" when only one pointer references the object.
int use_count () const throw ()
 Returns how many pointers are sharing the object referenced by "this".
bool ok () const throw ()
 Verifies the invariant for class lkptr<X>.

Private Member Functions

 base_lkptr (X *p=0) throw ()
 Default constructor and constructor from a regular pointer.
template<typename Y >
 base_lkptr (Y *p) throw ()
 Constructor from a pointer to a derived class.
 base_lkptr (const base_lkptr &r) throw ()
 Copy constructor: share the object with other pointers.
template<typename Y >
 base_lkptr (const base_lkptr< Y > &r) throw ()
 Copy constructor from a derived clase: share the object with other pointers.
 ~base_lkptr ()
 Destructor.
void acquire (base_lkptr *r) throw ()
 Makes this->ptr point to r.ptr.
void unlink ()
 Unlink from pointer chain.
void autolink ()
 Autolink: unique() becomes true.
void merge (base_lkptr &r)
 Blends together *this and r when both point to the same object.

Private Attributes

X * ptr
 Pointer to referenced object (can be a NULL pointer).
base_lkptr * prev
 Next in pointer chain.
base_lkptr * next
 Previous in pointer chain.

Friends

class lkptr
class array_lkptr
class wide_lkptr
class weak_lkptr
class test_lkptr
template<typename Y >
bool check_ok (const base_lkptr< Y > &p) throw ()

Detailed Description

template<typename X>
class base_lkptr< X >

Accesory class that contains the fields all lkptr<> intelligent pointers.

Definition at line 169 of file lkptr.h.

Constructor & Destructor Documentation

template<typename X>
base_lkptr< X >::base_lkptr ( X *  p = 0) throw () [inline, explicit, private]

Default constructor and constructor from a regular pointer.

Definition at line 185 of file lkptr.h.

template<typename X>
template<typename Y >
base_lkptr< X >::base_lkptr ( Y *  p) throw () [inline, explicit, private]

Constructor from a pointer to a derived class.

  • Check that the pointer is not null when types are not compatible.
  • Make sure the destructor for the base class is virtual.

Definition at line 191 of file lkptr.h.

template<typename X>
base_lkptr< X >::base_lkptr ( const base_lkptr< X > &  r) throw () [inline, private]

Copy constructor: share the object with other pointers.

Definition at line 195 of file lkptr.h.

template<typename X>
template<typename Y >
base_lkptr< X >::base_lkptr ( const base_lkptr< Y > &  r) throw () [inline, explicit, private]

Copy constructor from a derived clase: share the object with other pointers.

  • Check that the pointer is not null when types are not compatible.
  • Make sure the destructor for the base class is virtual.

Definition at line 202 of file lkptr.h.

template<typename X>
base_lkptr< X >::~base_lkptr ( ) [inline, private]

Destructor.

Delete only if last reference.

  • The derived lkptr<>'s do the destruction.

Definition at line 214 of file lkptr.h.

Member Function Documentation

template<typename X>
void base_lkptr< X >::acquire ( base_lkptr< X > *  r) throw () [inline, private]

Makes this->ptr point to r.ptr.

  • Insert "this" after "r" in the double chained pointer list.
  • If called after fast_release() will restore the invariant into "this".
  • Will link (this <--> r) even when r->ptr is a NULL pointer.

Definition at line 220 of file lkptr.h.

template<typename X>
void base_lkptr< X >::unlink ( ) [inline, private]

Unlink from pointer chain.

Definition at line 231 of file lkptr.h.

template<typename X>
void base_lkptr< X >::autolink ( ) [inline, private]

Autolink: unique() becomes true.

Definition at line 236 of file lkptr.h.

template<typename X >
void base_lkptr< X >::merge ( base_lkptr< X > &  r) [private]

Blends together *this and r when both point to the same object.

  • Should never be needed because it is erroneous to have unrelated lkptr<>'s to the same object. This should be an error!
  • Very usefull to avoid multiple destruction from unrelated lkptr<>'s that reference the same object.
  • Will not blend together null pointers.
  • Requires linear time in the number use_count() of the lkptr<>'s to merge.

Definition at line 309 of file lkptr.h.

template<typename X>
X* base_lkptr< X >::get ( ) const throw () [inline]

Returns a pointer to referenced object.

Definition at line 279 of file lkptr.h.

template<typename X>
X& base_lkptr< X >::value ( ) const throw () [inline]

Returns the referenced object.

Definition at line 280 of file lkptr.h.

template<typename X>
X& base_lkptr< X >::operator* ( ) const throw () [inline]

Returns the referenced object.

Definition at line 281 of file lkptr.h.

template<typename X>
X* base_lkptr< X >::operator-> ( ) const throw () [inline]

Returns a pointer to referenced object.

Definition at line 282 of file lkptr.h.

template<typename X>
bool base_lkptr< X >::isNull ( ) const throw () [inline]

Returns true if the object pointed is null and false otherwise.

Definition at line 286 of file lkptr.h.

template<typename X>
bool base_lkptr< X >::unique ( ) const throw () [inline]

Return "true" when only one pointer references the object.

Definition at line 289 of file lkptr.h.

template<typename X >
int base_lkptr< X >::use_count ( ) const throw ()

Returns how many pointers are sharing the object referenced by "this". 

{{  // test::null_3x1
    lkptr<X> A, B, C;
    A = B = C;
    assertTrue( A.ok() );   assertTrue( check_ok(A) );
    assertTrue( B.ok() );   assertTrue( check_ok(C) );
    assertTrue( C.ok() );   assertTrue( check_ok(C) );

    assertTrue( A.use_count() == 3 );
    assertTrue( B.use_count() == 3 );
    assertTrue( C.use_count() == 3 );

    assertTrue( A == B );
    assertTrue( B == C );
    assertTrue( A.get() == 0 && A.isNull() );

    assertTrue( A.use_count() == 3 );
    assertTrue( B.use_count() == 3 );
    assertTrue( C.use_count() == 3 );
}}

Definition at line 352 of file lkptr.h.

template<typename X >
bool base_lkptr< X >::ok ( ) const throw ()

Verifies the invariant for class lkptr<X>.

  • Returns "true" when "p" contains a correct value.
  • It could return "true" even when it's value is corrupted.
  • it could never return if the value in "p" is corrupted.
Rep: Description with words.
  • Field "ptr" is the pointer to the referenced object.
  • All pointers that point to the same object are linked together.
  • The list is double linked to allow for O(1) insertion and removal.
  • There is no "first" or "last" element in the list. What it is important is to be "in" the list, not which position in it a particular lkptr<X> occupies.
Rep: Class diagram.
    <=================================>     <=============>
    |      p1        p2       p3      |     |      p4     |
    |    +-+-+     +-+-+     +-+-+    |     |    +-+-+    |
    <===>|*|*|<===>|*|*|<===>|*|*|<===>     <===>|*|*|<===>
         +-+-+     +-+-+     +-+-+               +-+-+
         | * |     | * |     | * |               | * |
         +-|-+     +-|-+     +-|-+               +-|-+
           |         |         |                   |
          \|/       \|/       \|/                 \|/
         +----------------------+      +----------------------+
         |     Shared object    |      |    Lonely Object     |
         +----------------------+      +----------------------+

     +--------+-------+  "ptr" points to the object
     |  prev  |       |
     +--------+  ptr  +
     |  next  |       |  "next" is next in chain
     +--------+-------+  "prev" is previous in chain
The invariant: Description with words.

  • Invariant (1) (broken link): A unique pointer should be self-linked with both next && prev pointing to itself (this).
  • Invariant (2) (broken link): the double linked pointer chain can never be broken.
  • Invariant (3) (broken ptr): Every pointer in the chain should reference the same object.
  • Invariant (4): chain is not a circular double linked chain

Definition at line 407 of file lkptr.h.

Friends And Related Function Documentation

template<typename X>
friend class lkptr [friend]

Definition at line 170 of file lkptr.h.

template<typename X>
friend class array_lkptr [friend]

Definition at line 171 of file lkptr.h.

template<typename X>
friend class wide_lkptr [friend]

Definition at line 172 of file lkptr.h.

template<typename X>
friend class weak_lkptr [friend]

Definition at line 173 of file lkptr.h.

template<typename X>
friend class test_lkptr [friend]

Definition at line 174 of file lkptr.h.

template<typename X>
template<typename Y >
bool check_ok ( const base_lkptr< Y > &  p) throw () [friend]

Member Data Documentation

template<typename X>
X* base_lkptr< X >::ptr [private]

Pointer to referenced object (can be a NULL pointer).

Definition at line 177 of file lkptr.h.

template<typename X>
base_lkptr* base_lkptr< X >::prev [private]

Next in pointer chain.

Definition at line 178 of file lkptr.h.

template<typename X>
base_lkptr* base_lkptr< X >::next [private]

Previous in pointer chain.

Definition at line 179 of file lkptr.h.

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Friends Defines
Generated on Mon Jun 20 2011 09:59:13 for lkptr - simple reference LinKed PoinTeR: by  doxygen 1.7.4