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.
Public Member Functions
	lkptr (X *p=0) throw ()
	Default constructor and constructor from a regular pointer.
	~lkptr ()
	Destructor. Delete only if last reference.
	lkptr (const lkptr &r) throw ()
	Copy constructor: share the object with other pointers.
lkptr &	operator= (const lkptr &r)
	Copy operator: share the object with other pointers.
void	swap (lkptr &r) throw ()
	Swaps with r.
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.
	operator X * () 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".
void	release ()
	Releases the object.
void	weak_release ()
	Releases the object.
void	reset (X *p=0)
	Resets the pointer so that it will point to "p".
bool	ok () const throw ()
	Verifies the invariant for class lkptr<X>.
Private Member Functions
void	acquire (lkptr *r) throw ()
	Makes this->m_ptr point to r.m_ptr.
void	fast_release ()
	Releases the object.
Private Attributes
X *	m_ptr
	Pointer to referenced object (can be a NULL pointer).
lkptr *	m_prev
	Next in pointer chain.
lkptr *	m_next
	Previous in pointer chain.
Friends
class	test_lkptr
	Test lkptr<X>.
template<class Y>
bool	check_ok (const lkptr< Y > &p) throw ()
	Verifies the invariant for class lkptr<Y>.

---

Detailed Description

template<class 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 102 of file lkptr.h.

---

Member Typedef Documentation

template<class X>

typedef X lkptr< X >::element_type

Standard name for the pointed object.

Definition at line 108 of file lkptr.h.

template<class X>

typedef X lkptr< X >::value_type

Standard name for the pointed object.

Definition at line 109 of file lkptr.h.

---

Constructor & Destructor Documentation

template<class X>

lkptr< X >::lkptr

(

X *

p = 0

)

throw () [inline, explicit]

Default constructor and constructor from a regular pointer.

Definition at line 112 of file lkptr.h.

template<class X>

lkptr< X >::~lkptr

(

)

[inline]

Destructor. Delete only if last reference.

Definition at line 113 of file lkptr.h.

template<class X>

lkptr< X >::lkptr

(

const lkptr< X > &

r

)

throw () [inline]

Copy constructor: share the object with other pointers.

Definition at line 116 of file lkptr.h.

---

Member Function Documentation

template<class X>

lkptr& lkptr< X >::operator=

(

const lkptr< X > &

r

)

[inline]

Copy operator: share the object with other pointers.

Definition at line 118 of file lkptr.h.

template<class X>

void lkptr< X >::swap

(

lkptr< X > &

r

)

throw () [inline]

Swaps with r.

Definition at line 233 of file lkptr.h.

template<class X>

X* lkptr< X >::get

(

)

const throw () [inline]

Returns a pointer to referenced object.

Definition at line 141 of file lkptr.h.

template<class X>

X& lkptr< X >::value

(

)

const throw () [inline]

Returns the referenced object.

Definition at line 142 of file lkptr.h.

template<class X>

X& lkptr< X >::operator*

(

)

const throw () [inline]

Returns the referenced object.

Definition at line 143 of file lkptr.h.

template<class X>

X* lkptr< X >::operator->

(

)

const throw () [inline]

Returns a pointer to referenced object.

Definition at line 144 of file lkptr.h.

template<class X>

lkptr< X >::operator X *

(

)

const throw () [inline]

Returns a pointer to referenced object.

Definition at line 145 of file lkptr.h.

template<class X>

bool lkptr< X >::isNull

(

)

const throw () [inline]

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

Definition at line 148 of file lkptr.h.

template<class X>

bool lkptr< X >::unique

(

)

const throw () [inline]

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

Definition at line 151 of file lkptr.h.

template<class X>

int lkptr< X >::use_count

(

)

const throw () [inline]

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

Definition at line 301 of file lkptr.h.

template<class 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 160 of file lkptr.h.

template<class X>

void lkptr< X >::weak_release

(

)

[inline]

Releases the object.

• Before: If this was the last reference, it will not delete the referenced object.
• After: The pointer becomes NULL.
• After: Simliar to reset(0) (with no delete).
• Difference: never deletes the pointed object.

Definition at line 171 of file lkptr.h.

template<class 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".

Definition at line 182 of file lkptr.h.

template<class 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 "m_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     |
         +----------------------+      +----------------------+

     +--------+-------+  "m_ptr" points to the object
     | m_prev |       |
     +--------+ m_ptr +
     | m_next |       |  "m_next" is next in chain
     +--------+-------+  "m_prev" is previous in chain

The invariant: Description with words.

• Invariant (1) (broken link): A unique pointer should be self-linked with both m_next && m_prev pointing to itself (this).

• Invariant (2) (broken link): the double linked pointer can never be broken.

• Invariant (3) (broken m_ptr): Every pointer in the chain should reference the same object.

Definition at line 356 of file lkptr.h.

template<class X>

void lkptr< X >::acquire

(

lkptr< X > *

r

)

throw () [inline, private]

Makes this->m_ptr point to r.m_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->m_ptr is a NULL pointer.

Definition at line 199 of file lkptr.h.

template<class X>

void lkptr< X >::fast_release

(

)

[inline, private]

Releases the object.

• If this->m_ptr is the last reference, it also deletes the object.
• Leaves all the fields in "this" in a broken state.
• Caller must ensure that all the fields get good values after invocation.

Definition at line 213 of file lkptr.h.

---

Friends And Related Function Documentation

template<class X>

friend class test_lkptr [friend]

Test lkptr<X>.

Definition at line 228 of file lkptr.h.

template<class X>

template<class Y>

bool check_ok

(

const lkptr< Y > &

p

)

throw () [friend]

Verifies the invariant for class lkptr<Y>.

See also:

lkptr<Y>::ok().

Definition at line 314 of file lkptr.h.

---

Member Data Documentation

template<class X>

X* lkptr< X >::m_ptr [private]

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

Definition at line 104 of file lkptr.h.

template<class X>

lkptr* lkptr< X >::m_prev [private]

Next in pointer chain.

Definition at line 105 of file lkptr.h.

template<class X>

lkptr* lkptr< X >::m_next [private]

Previous in pointer chain.

Definition at line 106 of file lkptr.h.

---

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

• lkptr.h