Polaris: Wrapper Class Reference

Wrapper Class Reference

Class to hold Listable objects in Collections. More...

#include <Wrapper.h>

Inheritance diagram for Wrapper:

[legend]List of all members.


Public Member Functions
	Wrapper ()
virtual	~Wrapper ()
	Deletes objects and Wrappers if no one is pointing to them.
Wrapper *	next_ref () const
	retrieve next Wrapper.
void	next (const Wrapper *newnext)
	set next Wrapper and adjust reference counts.
Wrapper *	prev_ref () const
	retrieve previous Wrapper.
void	prev (const Wrapper *newprev)
	set previous Wrapper and adjust reference counts.
void	ref_inc ()
	Increment the reference count.
void	ref_dec ()
	Decrement the reference count.
int	count () const
	Return the reference count.
void	unlink ()
	remove ourself from any list we may be in
Listable *	object () const
	Return the Wrapper's object or report an error if invalid (Redeclared since object(Listable *) hides the original declared in ProtoWrapper).
virtual void	object (const Listable *newobject)
	Set Wrapper's object to newobject.
virtual int	is_live_wrapper () const
	Is wrapper a live wrapper or a reference wrapper?
virtual Wrapper *	clone () const
	Return a copy of the wrapper and possibly the object.
virtual void	delete_object ()
	Get rid of object--LiveWrapper should delete or Zombie it and RefWrapper should NULL its link to it.
virtual void *	key_node () const
	only for KeyWrappers.
virtual void	key_node (void *new_node)
	only for KeyWrappers.
Protected Member Functions
void	_ref_dec_delete ()
	No more references to wrapper so it should be deleted.
virtual int	_is_proto_wrapper () const
	Is this wrapper a ProtoWrapper?
Protected Attributes
Wrapper *	_next
Wrapper *	_prev
	Listable *_ptr; // Inherited from ProtoWrapper Pointer to object.
int	_refs
	Number of references to the Wrapper--this should count every structure\'s pointer to the wrapper including Wrapper links, iterators and owner pointers from owned objects.

Detailed Description

Class to hold Listable objects in Collections.

Polaris C++ VDL

See also:: Wrapper.h
Wrapper.cc

Overview

The Wrapper class is responsible for maintaining objects while in any Collection class. Wrappers perform all operations required for ownership indication, reference counting and for representing deleted objects in the form of Zombies.

Description

The underlying formula for the Collection hierarchy is that Collections hold wrappers rather than the objects themselves. When an object is placed in a Collection, a new wrapper is created and the object is manipulated through the wrapper. The Listable class contributes a standardized interface to the Wrapper classes and the Collection hierarchy, and, thus, for an object to be contained by a wrapper, it must derive from Listable.

Both Wrappers to take ownership of objects (LiveWrappers) and Wrappers which hold references to objects already owned (RefWrappers) are derived from this class as well as Wrappers to be used with Maps and Databases (KeyWrappers). All collections maintain objects via lists of wrappers (this also provides the interface for Iterators). All operations required for maintaining this list are also defined here.

Wrappers also control the automatic deletion of objects if their reference count falls to 0. Similarly, if an object is deleted which still has outstanding references to it, the Wrapper will catch this and turn the object into a Zombie object (a memory- efficient Listable form) which is used to trap references to the deleted object.

Programmer Notes

Bear in mind that calling dec() on a wrapper may result in it being deleted. Thus, in cases where a reference is moving from one node to another, it is far better to increment the new node and then decrement the old node instead of the other way around. If it is done the other way, that stage where the reference does not exist could result in a chain reaction of deletions which could delete the node about to be incremeneted and result in a crash!

Constructor & Destructor Documentation

Wrapper::Wrapper ( ) [inline]

Definition at line 156 of file Wrapper.h.
References _next, _prev, _refs, and register_instance().

Wrapper::~Wrapper ( ) [virtual]

Deletes objects and Wrappers if no one is pointing to them.
Relinks our next and prev together.
Definition at line 10 of file Wrapper.cc.
References _refs, and unregister_instance().

Member Function Documentation

void Wrapper::_ref_dec_delete ( ) [protected]

No more references to wrapper so it should be deleted.

Definition at line 77 of file Wrapper.cc.
References _next, _prev, next(), and prev().
Referenced by ref_dec().

int Wrapper::_is_proto_wrapper ( ) const [protected, virtual]

Is this wrapper a ProtoWrapper?

Reimplemented from ProtoWrapper.
Definition at line 113 of file Wrapper.cc.
Referenced by next(), prev(), and prev_ref().

Wrapper * Wrapper::next_ref ( ) const [inline]

retrieve next Wrapper.
< p_assert(!_is_proto_wrapper(), "Attempt to access next_ref() in a" " ProtoWrapper. Probably an illegal use of a Ref/Element");
Definition at line 167 of file Wrapper.h.
References _next.
Referenced by BaseRefList::_find_wrapper(), BaseRefList::_ins_before(), BaseMap::_insert_before(), BaseRefMap::_list_insert(), BaseMap::_list_insert(), Collection::_unlink_wrapper(), BaseList::assign(), Collection::clear(), BaseRefList::del(), Collection::index(), BaseList::ins_before(), BaseList::modify(), Listable::next_ref(), BaseList::next_ref(), Collection::operator[](), Collection::structures_OK(), and Collection::valid().

void Wrapper::next ( const Wrapper * newnext )

set next Wrapper and adjust reference counts.
... have to assign newnext first so we don\'t get stuck in an ... infinite loop of deletion
... next IS NOT being NULLed
... There is no old next
... new next gets a ref
... The old next is being replaced
... new next gets a ref
... old next looses a ref
... next being set to NULL
... old next looses a ref
Definition at line 21 of file Wrapper.cc.
References _is_proto_wrapper(), _next, ref_dec(), and ref_inc().
Referenced by BaseRefList::_ins_before(), BaseMap::_insert_after(), BaseRefMap::_list_insert(), BaseMap::_list_insert(), _ref_dec_delete(), BaseList::ins_before(), BaseList::make_static_list(), and unlink().

Wrapper * Wrapper::prev_ref ( ) const [inline]

retrieve previous Wrapper.

Definition at line 175 of file Wrapper.h.
References _is_proto_wrapper(), and _prev.
Referenced by BaseRefList::_ins_before(), BaseMap::_insert_after(), Collection::_unlink_wrapper(), BaseList::assign(), BaseList::ins_before(), BaseList::make_static_list(), Collection::operator[](), Listable::prev_ref(), BaseList::prev_ref(), and Collection::structures_OK().

void Wrapper::prev ( const Wrapper * newprev )

set previous Wrapper and adjust reference counts.
... prev IS NOT being NULLed
... There is no old prev
... new prev gets a ref
... The old prev is being replaced
... new prev gets a ref
... old prev looses a ref
... prev being set to NULL
... old prev looses a ref
Definition at line 51 of file Wrapper.cc.
References _is_proto_wrapper(), _prev, ref_dec(), and ref_inc().
Referenced by BaseRefList::_ins_before(), BaseMap::_insert_before(), BaseRefMap::_list_insert(), BaseMap::_list_insert(), _ref_dec_delete(), BaseList::ins_before(), BaseList::make_static_list(), and unlink().

void Wrapper::ref_inc ( ) [inline]

Increment the reference count.

Definition at line 183 of file Wrapper.h.
References _refs.
Referenced by BaseRefList::_ins_before(), BaseMap::_insert_after(), BaseMap::_insert_before(), BaseRefMap::_list_insert(), BaseMap::_list_insert(), Collection::_unlink_wrapper(), Assign< T >::Assign(), BaseList::ins_before(), BaseList::make_static_list(), next(), LiveWrapper::object(), BaseIter::operator=(), prev(), BaseIter::reset(), and BaseIter::set_to_last().

void Wrapper::ref_dec ( ) [inline]

Decrement the reference count.
< This wrapper is no longer needed by anyone.
Definition at line 195 of file Wrapper.h.
References _ref_dec_delete(), and _refs.
Referenced by BaseRefList::_ins_before(), BaseMap::_insert_after(), BaseMap::_insert_before(), BaseRefMap::_list_insert(), BaseMap::_list_insert(), _listable_ref_dec(), Collection::_unlink_wrapper(), Collection::clear(), LiveWrapper::delete_object(), BaseList::ins_before(), LiveWrapper::loose_object(), BaseList::make_static_list(), next(), BaseIter::operator=(), prev(), BaseIter::reset(), BaseIter::set_to_last(), BaseIter::~BaseIter(), and UntypedAssign::~UntypedAssign().

int Wrapper::count ( ) const [inline]

Return the reference count.

Definition at line 189 of file Wrapper.h.
References _refs.

void Wrapper::unlink ( )

remove ourself from any list we may be in
This does not effect our next or prev.
Definition at line 89 of file Wrapper.cc.
References _next, _prev, next(), and prev().
Referenced by Collection::_unlink_wrapper().

Listable * Wrapper::object ( ) const [inline]

Return the Wrapper's object or report an error if invalid (Redeclared since object(Listable *) hides the original declared in ProtoWrapper).

Reimplemented from ProtoWrapper.
Reimplemented in LiveWrapper, and RefWrapper.
Definition at line 203 of file Wrapper.h.
References ProtoWrapper::object().
Referenced by BaseList::assign(), BaseIter::assign(), BaseIter::current(), BaseMapIter::current_data(), BaseMapRoot::find_ref(), Collection::first_ref(), BaseIter::grab(), BaseList::ins(), BaseList::ins_after(), BaseList::ins_before(), Collection::last_ref(), BaseList::make_static_list(), BaseList::modify(), BaseIter::modify(), Listable::next_ref(), BaseList::next_ref(), RefWrapper::object(), LiveWrapper::object(), Assign< T >::operator=(), Collection::operator[](), Listable::prev_ref(), BaseList::prev_ref(), BaseIter::pull(), BaseMapRoot::remove(), and Collection::structures_OK().

virtual void Wrapper::object ( const Listable * newobject ) [virtual]

Set Wrapper's object to newobject.
Updates our ref count--for LiveWrapper, Sets newobject's owner pointer.
Reimplemented in LiveWrapper, and RefWrapper.

int Wrapper::is_live_wrapper ( ) const [virtual]

Is wrapper a live wrapper or a reference wrapper?

Reimplemented in LiveWrapper, and RefWrapper.
Definition at line 149 of file Wrapper.cc.
Referenced by Collection::clear(), BaseIter::grab(), BaseIter::modify(), BaseIter::modify_in_place(), and BaseIter::pull().

Wrapper * Wrapper::clone ( ) const [virtual]

Return a copy of the wrapper and possibly the object.

Reimplemented in LiveWrapper, and RefWrapper.
Definition at line 142 of file Wrapper.cc.

void Wrapper::delete_object ( ) [virtual]

Get rid of object--LiveWrapper should delete or Zombie it and RefWrapper should NULL its link to it.

Reimplemented in LiveWrapper, and RefWrapper.
Definition at line 136 of file Wrapper.cc.
Referenced by BaseRefList::_del(), BaseList::_del(), Collection::clear(), and BaseIter::del().

void * Wrapper::key_node ( ) const [virtual]

only for KeyWrappers.

Reimplemented in LiveKeyWrapper, and RefKeyWrapper.
Definition at line 121 of file Wrapper.cc.
Referenced by BaseIter::current_key(), and BaseMapRoot::key_ref().

virtual void Wrapper::key_node ( void * new_node ) [virtual]

only for KeyWrappers.

Reimplemented in LiveKeyWrapper, and RefKeyWrapper.

Member Data Documentation

Wrapper* Wrapper::_next [protected]

Definition at line 73 of file Wrapper.h.
Referenced by _ref_dec_delete(), RefWrapper::clone(), LiveWrapper::clone(), next(), next_ref(), unlink(), and Wrapper().

Wrapper * Wrapper::_prev [protected]

Listable *_ptr; // Inherited from ProtoWrapper Pointer to object.
New rule: for a LiveWrapper, _ptr will always point to a valid object or will be NULL (i.e. never point to Zombie). For a RefWrapper: _ptr can point to an object or a Zombie (not sure if ever needs to be NULL).
Definition at line 73 of file Wrapper.h.
Referenced by _ref_dec_delete(), RefWrapper::clone(), LiveWrapper::clone(), prev(), prev_ref(), unlink(), and Wrapper().

int Wrapper::_refs [protected]

Number of references to the Wrapper--this should count every structure\'s pointer to the wrapper including Wrapper links, iterators and owner pointers from owned objects.
next( ) and prev( ) maintain the counts of _next and _prev and Collection::set_wrapper( ) maintains count of parent pointers.
Definition at line 84 of file Wrapper.h.
Referenced by RefWrapper::clone(), LiveWrapper::clone(), count(), ref_dec(), ref_inc(), Wrapper(), and ~Wrapper().

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

Fri Mar 25 23:08:43 2005

Wrapper Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes