lkptr< X > Class Template Reference

These smart pointer share the object they point to. More...

#include <lkptr.h>

List of all members.

Public Types
typedef X	element_type
	Standard name for the pointed object.
typedef X	value_type
	Standard name for the pointed object.
typedef X *	pointer
	Standard name for the pointer to the object.
Public Member Functions
	lkptr (X *p=0) throw ()
template<typename Y >
	lkptr (Y *p) throw ()
	lkptr (const lkptr &r) throw ()
template<typename Y >
	lkptr (const lkptr< Y > &r) throw ()
	~lkptr ()
	Destructor.
lkptr &	operator= (const lkptr &r)
	Copy operator: share the object with other pointers.
template<typename Y >
lkptr &	operator= (const lkptr< Y > &r)
	Copy operator from a derived clase: share the object with other pointers.
void	swap (lkptr &r) throw ()
	Swaps with r.
X *	get () const throw ()
X &	value () const throw ()
X &	operator* () const throw ()
X *	operator-> () const throw ()
bool	isNull () const throw ()
bool	unique () const throw ()
int	use_count () const throw ()
void	release ()
	Releases the object.
void	reset (X *p=0)
	Resets the pointer so that it will point to "p".
void	reset (const lkptr &r)
	(*this) = r.
template<typename Y >
void	reset (const lkptr< Y > &r)
	(*this) = r [ from a derived class ].
bool	ok () const throw ()
Private Attributes
base_lkptr< X >	b
	Contains the 3 pointers for the lkptr<>.
Friends
class	lkptr
class	test_lkptr
	Test lkptr<X>.
template<typename Y >
bool	check_ok (const lkptr< Y > &p) throw ()

---

Detailed Description

template<typename X>
class lkptr< X >

These smart pointer share the object they point to.

Only after the last pointer releases its reference will the object be deleted.

• Whenever the object will be changed by one of the pointers, all the other pointers will also see the change.
• The implementation stores three pointers for every lkptr, but does not allocate anything on the free store.
• Every lkptr is implemented using 3 internal pointers which makes it 3 times as big as a regular pointer. In exchange, automatic garbage collection is provided by the C++ constructor - destructor protocol of execution.
• These pointers are double linked together. When only one pointer is in the chain, then the object will be deleted if the pointer releases it. Otherwise, the object will not be deleted because the other pointers in the chain are still referencing it.
• These pointers are not intrusive, because they do not need an extra field in the pointed object to keep track of how many pointers reference the same object.
• These pointers do not allocate extra memory to keep track of the reference count, because the linked list itself binds together all pointers that reference the same object.
• A diagram for the pointer chain is shown in the documentation for method ok().
• Many of the pointer operators will never throw exceptions (hence the "throw()" especification in the method signature).
• Memory leaks are extremely rare. Reference counting/linking can leak in the case of circular references (i.e., when the pointed object itself contains a counted/linked pointer, which points to an object that contains the original counted/linked pointer).
• These pointers cannot be used in ROM memory because they modify each other when double linking, even if they are const.

Usage:

void foo() {
    lkptr<AnyClass> p(new AnyClass); // "p" is one smart-pointer
    lkptr<AnyClass> q;               // "q" is the other smart-pointer

    p->DoSomething();               // no syntax change when using pointers
    q = p;                          // share the object
    q->Change();                    // both "*p" && "*q" get changed
    p = q;                          // both still point to the same object
    lkptr<AnyClass> r = p;          // The 3 of them share the same object

    // delete p; // No need to worry about destruction
    // delete q; // the lkptr<> destructor will handle deletions for you.
    // delete r;
}

• This work is based on Sharon's paper:
  • "Smart Pointers - What, Why, Which?"
  • http://ootips.org/yonat/4dev/smart-pointers.html
  • Yonat Sharon <yonat@ootips.org>
  • 1999.

Definition at line 485 of file lkptr.h.

---

Member Typedef Documentation

template<typename X>

typedef X lkptr< X >::element_type

Standard name for the pointed object.

Definition at line 490 of file lkptr.h.

template<typename X>

typedef X lkptr< X >::value_type

Standard name for the pointed object.

Definition at line 491 of file lkptr.h.

template<typename X>

typedef X* lkptr< X >::pointer

Standard name for the pointer to the object.

Definition at line 492 of file lkptr.h.

---

Constructor & Destructor Documentation

template<typename X>

lkptr< X >::lkptr

(

X *

p = 0

)

throw () [inline, explicit]

Default constructor and constructor from a regular pointer.

.

Definition at line 495 of file lkptr.h.

template<typename X>

template<typename Y >

lkptr< X >::lkptr

(

Y *

p

)

throw () [inline, explicit]

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 499 of file lkptr.h.

template<typename X>

lkptr< X >::lkptr

(

const lkptr< X > &

r

)

throw () [inline]

Copy constructor: share the object with other pointers.

.

Definition at line 502 of file lkptr.h.

template<typename X>

template<typename Y >

lkptr< X >::lkptr

(

const lkptr< Y > &

r

)

throw () [inline, explicit]

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 506 of file lkptr.h.

template<typename X>

lkptr< X >::~lkptr

(

)

[inline]

Destructor.

Definition at line 508 of file lkptr.h.

---

Member Function Documentation

template<typename X>

lkptr& lkptr< X >::operator=

(

const lkptr< X > &

r

)

[inline]

Copy operator: share the object with other pointers.

Definition at line 518 of file lkptr.h.

template<typename X>

template<typename Y >

lkptr& lkptr< X >::operator=

(

const lkptr< Y > &

r

)

[inline]

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

• Will not copy when types are not compatible.
• Make sure the destructor for the base class is virtual.

Definition at line 554 of file lkptr.h.

template<typename X >

void lkptr< X >::swap

(

lkptr< X > &

r

)

throw ()

Swaps with r.

Definition at line 670 of file lkptr.h.

template<typename X>

X* lkptr< X >::get

(

)

const throw () [inline]

Returns a pointer to referenced object.

.

Definition at line 564 of file lkptr.h.

template<typename X>

X& lkptr< X >::value

(

)

const throw () [inline]

Returns the referenced object.

.

Definition at line 565 of file lkptr.h.

template<typename X>

X& lkptr< X >::operator*

(

)

const throw () [inline]

Returns the referenced object.

.

Definition at line 566 of file lkptr.h.

template<typename X>

X* lkptr< X >::operator->

(

)

const throw () [inline]

Returns a pointer to referenced object.

.

Definition at line 567 of file lkptr.h.

template<typename X>

bool lkptr< X >::isNull

(

)

const throw () [inline]

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

.

Definition at line 570 of file lkptr.h.

template<typename X>

bool lkptr< X >::unique

(

)

const throw () [inline]

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

.

Definition at line 571 of file lkptr.h.

template<typename X>

int lkptr< X >::use_count

(

)

const throw () [inline]

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 572 of file lkptr.h.

template<typename X>

void lkptr< X >::release

(

)

[inline]

Releases the object.

• Before: If this was the last reference, it also deletes the referenced object.
• After: The pointer becomes NULL.
• After: Equivalent to reset(0).

Definition at line 578 of file lkptr.h.

template<typename X>

void lkptr< X >::reset

(

X *

p = 0

)

[inline]

Resets the pointer so that it will point to "p".

• Before: If this was the last reference, it also deletes the referenced object.
• Before: "p==0" is a valid argument (NULL is ok).
• After: The object pointed by "p" gets to be own by "this".
• [DANGER] V.reset( r.get() ) almost always is an error because both V and r will destroy the referenced object. Use V = r.

  struct Point                          { virtual int val() const { return 0; } };
    struct Circle      : public Point   { virtual int val() const { return 1; } };
      struct Cilinder  : public Circle  { virtual int val() const { return 2; } };
    struct Square      : public Point   { virtual int val() const { return 3; } };
      struct Rectangle : public Square  { virtual int val() const { return 4; } };
  

  {{  // test::inheritance
      lkptr<Point> VEC[5];
      VEC[0].reset(  new Point()         );
      VEC[1].reset(    new Circle()      );
      VEC[2].reset(      new Cilinder()  );
      VEC[3].reset(    new Square()      );
      VEC[4].reset(      new Rectangle() );
  
      for (int i=0; i<int(DIM(VEC)); ++i) {
          assertTrue( VEC[i]->val() == i );
          assertTrue( VEC[i].ok() );
      }
  }}
  

Definition at line 603 of file lkptr.h.

template<typename X>

void lkptr< X >::reset

(

const lkptr< X > &

r

)

[inline]

(*this) = r.

Definition at line 614 of file lkptr.h.

template<typename X>

template<typename Y >

void lkptr< X >::reset

(

const lkptr< Y > &

r

)

[inline]

(*this) = r [ from a derived class ].

Definition at line 644 of file lkptr.h.

template<typename X>

bool lkptr< X >::ok

(

)

const throw () [inline]

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.

.

Definition at line 653 of file lkptr.h.

---

Friends And Related Function Documentation

template<typename X>

friend class lkptr [friend]

Definition at line 488 of file lkptr.h.

template<typename X>

friend class test_lkptr [friend]

Test lkptr<X>.

Definition at line 657 of file lkptr.h.

template<typename X>

template<typename Y >

bool check_ok

(

const lkptr< Y > &

p

)

throw () [friend]

---

Member Data Documentation

template<typename X>

base_lkptr<X> lkptr< X >::b [private]

Contains the 3 pointers for the lkptr<>.

Definition at line 486 of file lkptr.h.

---

The documentation for this class was generated from the following file:

• lkptr.h