---

MangoPtr::Owned< CntrType, oshiptype > Class Template Reference

#include <OwnedCntr.hh>

Inheritance diagram for MangoPtr::Owned< CntrType, oshiptype >:

[legend]Collaboration diagram for MangoPtr::Owned< CntrType, oshiptype >:

[legend]List of all members.

---

Detailed Description

template<typename CntrType, OwnershipType oshiptype>
class MangoPtr::Owned< CntrType, oshiptype >

Owned container of pointers.

When the owner (i.e. the owned container) goes out of scope,each element in the container is destroyed via a call to delete. The container must have an iterator type defined with begin(), end() and prefix increment defined for the iterator.

The idiom that is designed into Owned<Container> is:

• create an owned container of pointers in a class or as a local variable;
• access the container data/methods via the ()-> operation, as in ownedList()->push_back(new int);
• avoid passing the owned container object around, instead either pass the pure container itself, as in

            struct SomeClass {
                typedef std::list<int*> List;
                Owned<List> ownedList;
                List& getList() const {return ownedList.cntr();}
            }
  

  or pass an BLink<Container>, as in

            struct SomeClass {
                Owned<List> ownedList;
                // one possibility
                void getList(BLink<List>& out) const {
                    out.tieTo( ownedList );
                }
                // another; a good compiler will use the return-value
                // optimizations to eliminate the temporaries
                BLink<List> getList() const {
                    return BLink<List>( ownedList );
                }
            }
  

• use the cntr() method to pass the non-owned container around

Note that the container can be several layers deep before containing pointers. For example,

        typedef std::list< std::vector<T*> > ListVec;
        typedef Owned<ListVec> OListComplex;

or even

        typedef Owned<std::map<T*, int> > OMapTP;
        typedef Owned<std:list<OMapTP*> > OListComplex;

Note also that the protected inheritence is purely to remind you that an owned container can be used with BLink.

Definition at line 89 of file OwnedCntr.hh.

Public Types
typedef CntrType	OwnedType
	Class of object held, a la auto_ptr.
Public Methods
Constructors
	Owned ()
	Default owns empty container.
	Owned (CntrType &)
	Take ownership of a container of pointers.
template<typename O2Type>	Owned (Ownership< O2Type, oshiptype >)
	Create an owner by taking ownership from another owner.
	~Owned ()
	Invalidate the BLink's tied to us, call delete on all pointers in the list, and destroy the container.
Mutators
void	swap (Owned &)
	Swap two owned containers.
void	swap (CntrType &)
	Swap an owned container with a non-owned container.
void	clear ()
	Clear the container.
void	unlink () const
	Unlink from all BLink objects linked to us.
void	reset ()
	Reset state to default constructor.
Ownership< CntrType, oshiptype >	transfer ()
	Accept to abandon ownership to another Owned.
void	takeOwnership (CntrType &)
	Take ownership of a container of pointers.
template<typename O2Type> void	takeOwnership (Ownership< O2Type, oshiptype >)
	Take ownership of a container from another Owned container that has given up ownership.
Utility methods
void	cloneObjNew (CntrType &) const
	Convenience method to create a deep-copied copy of the owned container, using new() (if you have defined a specialization of CntrCloner for your container element type and it is visible at the time of copy, that one will be used by the compiler instead of new()), into dest.
CntrType *	shareUsage (ValidityChecker &) const
	Other classes that may be able to share the usage of the container can do so by calling this method with a ValidityChecker.
CntrType &	cntr ()
	Use this method to get ref to container.
const CntrType &	cntr () const
	See also: The non-const version
CntrType *	operator() ()
	Use this method to get a pointer to container, never NULL.
const CntrType *	operator() () const
	See also: The non-const version

---

Constructor & Destructor Documentation

template<typename CntrType, OwnershipType oshiptype> MangoPtr::Owned< CntrType, oshiptype >::Owned (  CntrType &    cntr )  [inline, explicit]

Take ownership of a container of pointers. The cntr is transfered to Owned, meaning that after creation, the original container is empty. This requires an exception-safe, performant std::swap to be defined for CntrType. Definition at line 175 of file OwnedCntr.hh. References MangoPtr::Owned< CntrType, oshiptype >::cntr().

template<typename CntrType, OwnershipType oshiptype> template<typename O2Type> MangoPtr::Owned< CntrType, oshiptype >::Owned (  Ownership< O2Type, oshiptype >    os )  [inline, explicit]

Create an owner by taking ownership from another owner. Original owner looses ownership and ends up with an empty container. Parameters: os  the ownership being transfered Definition at line 189 of file OwnedCntr.hh.

template<typename CntrType, OwnershipType oshiptype> MangoPtr::Owned< CntrType, oshiptype >::~Owned (    )  [inline]

Invalidate the BLink's tied to us, call delete on all pointers in the list, and destroy the container. Implementation: Uses the method pointer to do the clean up. This supports default destructors for classes that want to use only a forward declaration of the container's element type. Definition at line 204 of file OwnedCntr.hh. References MangoPtr::SharedValidity::reset(), and MangoPtr::ValidityOwner::setValid().

---

Member Function Documentation

template<typename CntrType, OwnershipType oshiptype> void MangoPtr::Owned< CntrType, oshiptype >::swap (  Owned< CntrType, oshiptype > &    that )  [inline]

Swap two owned containers. CntrType must have std::swap defined for it. Note that if there are BLink objects tied to this owner, they will see the contents of their container swapped. This is identical to what would happen with normal pointers and refs: std::list<int> list1, list2; T* ptr = & list1; list1.swap(list2); // ptr still refers to list1, but content of // list1 is what used to be in list2 Definition at line 226 of file OwnedCntr.hh.

template<typename CntrType, OwnershipType oshiptype> void MangoPtr::Owned< CntrType, oshiptype >::swap (  CntrType &    that )  [inline]

Swap an owned container with a non-owned container. After the swap, the non-owned is owned and the owned is non-owned. Definition at line 239 of file OwnedCntr.hh.

template<typename CntrType, OwnershipType oshiptype> void MangoPtr::Owned< CntrType, oshiptype >::clear (    )  [inline]

Clear the container. This deletes all elements and empties the container. Definition at line 248 of file OwnedCntr.hh. Referenced by MangoPtr::Owned< CntrType, oshiptype >::reset(), and MangoPtr::Owned< CntrType, oshiptype >::takeOwnership().

template<typename CntrType, OwnershipType oshiptype> void MangoPtr::Owned< CntrType, oshiptype >::unlink (    )  const [inline]

Unlink from all BLink objects linked to us. This means that All BLink objects tied to this owned container will see isNull() == true All BLink objects that are (re)tied to this owned container will see isNotNull() == true. Definition at line 264 of file OwnedCntr.hh. Referenced by MangoPtr::Owned< CntrType, oshiptype >::reset().

template<typename CntrType, OwnershipType oshiptype> void MangoPtr::Owned< CntrType, oshiptype >::reset (    )  [inline]

Reset state to default constructor. This is equivalent to emptying the container, calling delete on the each element, and untying from all BLink object. All BLink objects tied to this owned container will see isNull() == true, and BLink objects are tied to this owner will not be tied to the same container as the other BLink's from before the reset(). Definition at line 280 of file OwnedCntr.hh. References MangoPtr::Owned< CntrType, oshiptype >::clear(), and MangoPtr::Owned< CntrType, oshiptype >::unlink(). Referenced by MangoPtr::Owned< CntrType, oshiptype >::takeOwnership(), and MangoPtr::Owned< CntrType &, OShared >::~Owned().

template<typename CntrType, OwnershipType oshiptype> Ownership< CntrType, oshiptype > MangoPtr::Owned< CntrType, oshiptype >::transfer (    )  [inline]

Accept to abandon ownership to another Owned. Use takeOwnership on the receiving owner to accept the transfer. Definition at line 291 of file OwnedCntr.hh.

template<typename CntrType, OwnershipType oshiptype> void MangoPtr::Owned< CntrType, oshiptype >::takeOwnership (  CntrType &    p )  [inline]

Take ownership of a container of pointers. Upon return, p is empty. std::swap is used for performance. Definition at line 302 of file OwnedCntr.hh. References MangoPtr::Owned< CntrType, oshiptype >::reset().

template<typename CntrType, OwnershipType oshiptype> void MangoPtr::Owned< CntrType, oshiptype >::cloneObjNew (  CntrType &    dest )  const [inline]

Convenience method to create a deep-copied copy of the owned container, using new() (if you have defined a specialization of CntrCloner for your container element type and it is visible at the time of copy, that one will be used by the compiler instead of new()), into dest. To clone into another owned container, use cloneObjNew(owned.cntr()). Precondition: dest must be empty Parameters: dest  the destination container Definition at line 332 of file OwnedCntr.hh.

template<typename CntrType, OwnershipType oshiptype> CntrType * MangoPtr::Owned< CntrType, oshiptype >::shareUsage (  ValidityChecker &    val )  const [inline]

Other classes that may be able to share the usage of the container can do so by calling this method with a ValidityChecker. The pointer returned is a pointer to the container. Note that this method is only to share usage, not ownership. Definition at line 348 of file OwnedCntr.hh. Referenced by MangoPtr::BLink< OType >::operator=().

template<typename CntrType, OwnershipType oshiptype> CntrType* MangoPtr::Owned< CntrType, oshiptype >::operator() (    )  [inline]

Use this method to get a pointer to container, never NULL. This maintains consistency with Owned<T*> type so that you use obj()->method() to call a method on the container, like you would if obj were an Owned<T*>. Definition at line 134 of file OwnedCntr.hh.

---

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

• OwnedCntr.hh

---