Referencia de la Clase lkptr< X >

These smart pointer share the object they point to. Más...

#include <lkptr.h>

Lista de todos los miembros.

Tipos públicos
typedef X	element_type
	Standard name for the pointed object.
Métodos públicos
	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.
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	refs () const throw ()
	Returns how many pointers are sharing the object referenced by "this".
void	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>.
Métodos privados
void	acquire (lkptr *r) throw ()
	Makes this->m_ptr point to r.m_ptr.
void	fast_release ()
	Releases the object.
Atributos privados
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.
Amigas
class	test_lkptr
template<class X>
bool	check_ok (const lkptr< X > &p) throw ()
	Verifies the invariant for class lkptr<X>.

---

Descripción detallada

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.

Definición en la línea 91 del archivo lkptr.h.

---

Documentación de los 'Tipos Definidos' miembros de la clase

template<class X>

typedef X lkptr< X >::element_type

Standard name for the pointed object.

Definición en la línea 97 del archivo lkptr.h.

---

Documentación del constructor y destructor

template<class X>

lkptr< X >::lkptr

(

X *

p = 0

)

throw () [inline, explicit]

Default constructor and constructor from a regular pointer.

Definición en la línea 100 del archivo lkptr.h.

template<class X>

lkptr< X >::~lkptr

(

)

[inline]

Destructor. Delete only if last reference.

Definición en la línea 101 del archivo lkptr.h.

template<class X>

lkptr< X >::lkptr

(

const lkptr< X > &

r

)

throw () [inline]

Copy constructor: share the object with other pointers.

Definición en la línea 104 del archivo lkptr.h.

---

Documentación de las funciones miembro

template<class X>

lkptr& lkptr< X >::operator=

(

const lkptr< X > &

r

)

[inline]

Copy operator: share the object with other pointers.

Definición en la línea 106 del archivo lkptr.h.

template<class X>

X* lkptr< X >::get

(

)

const throw () [inline]

Returns a pointer to referenced object.

Definición en la línea 119 del archivo lkptr.h.

template<class X>

X& lkptr< X >::value

(

)

const throw () [inline]

Returns the referenced object.

Definición en la línea 120 del archivo lkptr.h.

template<class X>

X& lkptr< X >::operator *

(

)

const throw () [inline]

Returns the referenced object.

Definición en la línea 121 del archivo lkptr.h.

template<class X>

X* lkptr< X >::operator->

(

)

const throw () [inline]

Returns a pointer to referenced object.

Definición en la línea 122 del archivo lkptr.h.

template<class X>

lkptr< X >::operator X *

(

)

const throw () [inline]

Returns a pointer to referenced object.

Definición en la línea 123 del archivo lkptr.h.

template<class X>

bool lkptr< X >::isNull

(

)

const throw () [inline]

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

Definición en la línea 126 del archivo lkptr.h.

template<class X>

bool lkptr< X >::unique

(

)

const throw () [inline]

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

Definición en la línea 129 del archivo lkptr.h.

template<class X>

int lkptr< X >::refs

(

)

const throw ()

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

Definición en la línea 211 del archivo 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 pointed to object becomes NULL.
• After: Equivalent to reset(0).

Definición en la línea 138 del archivo 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".

Definición en la línea 148 del archivo lkptr.h.

template<class X>

bool 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 "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.

Definición en la línea 266 del archivo 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.

Definición en la línea 165 del archivo 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.

Definición en la línea 179 del archivo lkptr.h.

---

Documentación de las funciones relacionadas y clases amigas

template<class X>

friend class test_lkptr [friend]

Definición en la línea 195 del archivo lkptr.h.

template<class X>

template<class X>

bool check_ok

(

const lkptr< X > &

p

)

throw () [friend]

Verifies the invariant for class lkptr<X>.

Ver también:

lkptr<X>::ok().

Definición en la línea 224 del archivo lkptr.h.

---

Documentación de los datos miembro

template<class X>

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

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

Definición en la línea 93 del archivo lkptr.h.

template<class X>

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

Next in pointer chain.

Definición en la línea 94 del archivo lkptr.h.

template<class X>

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

Previous in pointer chain.

Definición en la línea 95 del archivo lkptr.h.

---

La documentación para esta clase fué generada a partir del siguiente archivo:

• lkptr.h

---