---

MangoPtr::Owned< OType *, oshiptype > Class Template Reference

#include <OwnedPtr.hh>

Inheritance diagram for MangoPtr::Owned< OType *, oshiptype >:

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

[legend]List of all members.

---

Detailed Description

template<typename OType, OwnershipType oshiptype>
class MangoPtr::Owned< OType *, oshiptype >

An owned pointer, aka "an owner".

An owned pointer differs from a normal pointer in that it owns the resource associated with the pointer. It is therefore responsible for destroying the resource, for enforcing clear transfer of ownership, and for allowing users of the resource to test whether the resource has been destroyed before using it.

The ownership is either strict (MangoPtr::OStrict) or shared (MangoPtr::OShared). If strict, only one owner can have the resource, and it is destroyed at the same time as that owner. If shared, then several owners can own the same pointer, and the resource they own will be destroyed when the last of the owners is destroyed.

The most important methods of Owned<T*> are:

• constructors: default, and for taking ownership of a resource (via pointer, auto_ptr, etc).
• giveOwnership(): give ownership to another owner
• takeOwnership(): take ownership from another owner
• release(): tell owner(s) to forget about owning the resource

The raw pointer stored in the owner is accessed via Owned<T*>::operator(). This function provides a proxy to the pointer, of type MangoPtr::CheckedPtr<T>, that will assert (in debug mode) the non-nullness of the pointer if you dereference it. E.g., in

    Owned<Foo*> owner;
    owner()->callFooMethod();

the dereference (->) actually causes an assert(ptr in owner != NULL).

The resource usage can be shared with

• A MangoPtr::BLink<U>: when the owner is destroyed, thus destroying the resource, a BLink<U>::isNull() returns true, i.e. you should not use the "Better Link".
• Another object via shareUsage(): that object must store a MangoPtr::ValidityChecker; when the owner is destroyed, thus destroying the resource, a call to ValidityChecker::isValid() returns false, i.e. you should not use the resource shared.

Here is an example of using Owned<T*>. The assertions in the code are just to show what is true.

    struct Foo {
      // ...
      void doSomething() {}
    };

    int main()
    {
        BLink<Foo> p1;
        {
          // first clone owner1 using a call to new():
          Owned<Foo*> owner( new Foo );
          owner()->doSomething();
          
          // now tie p1 to owner
          p1.tieTo( owner );
          assert( p1.isNotNull() );
          p1()->doSomething(); // work with owned Foo
          
        } // owner dies, its Foo is destroyed

        // so its resource is no longer valid:
        assert( p1.isNull() );          
    }

Note that a function that expects an Owned<const T*> can be given an Owned<T*>, as would be legal with raw pointers:

        void func(const Owned<const T*>&); // will only use pointer
        void gunc(Owned<const T*>&); // will likely change ownership
        //...
        Owned<T*> owner;
        Owned<const T*> ownerConst;
        func(ownerConst);      // ok
        gunc(ownerConst);      // ok
        func(owner);           // ok, can convert
        gunc(owner);           // compile error since can't convert

Todo:

add std::swap specialization

Author:

Oliver Schoenborn

Since:

Feb 2002

Definition at line 49 of file OwnedPtr.hh.

Public Types
typedef OType	ObjectType
	Class of object held, a la auto_ptr.
Public Methods
	~Owned ()
	Free memory of pointee and invalidate.
Constructors
	Owned ()
	Empty owner, doens't own anything.
	Owned (const Owned &)
	Construct copy from an Owned of same type.
template<typename O2Type>	Owned (const Owned< O2Type, oshiptype > &)
	Construct copy from an Owned of derived type.
	Owned (OType *)
	Create owner of pointer p.
template<typename O2Type>	Owned (std::auto_ptr< O2Type > &)
	Take ownership of the pointee owned by a std::auto_ptr.
template<typename O2Type>	Owned (Ownership< O2Type, oshiptype >)
	Create an owner from an ownership Original owner looses ownership.
Mutators
void	swap (Owned &rhs)
	Swap with another owner rhs.
PType	release ()
	Release pointee from ownership by this Owned.
void	reset ()
	reset to default-construted state
Ownership< PType, oshiptype >	giveOwnership ()
	Give ownership to another object.
Owned &	operator= (const Owned &rhs)
	Assign from an owned pointer of different type. Only allowed for shared ownership.
template<typename O2Type> Owned &	operator= (const Owned< O2Type, oshiptype > &rhs)
	Assign from an owned pointer of different type Only allowed for shared ownership.
void	takeOwnership (OType *p)
	Assume ownership of a pointee.
template<typename O2Type> void	takeOwnership (std::auto_ptr< O2Type > &)
	Transfer ownership from a std::auto_ptr.
template<typename O2Type> void	takeOwnership (Ownership< O2Type, oshiptype >)
	Accept ownership from another Owned.
Utility methods
PType	cloneObjNew () const
	Get a dumb pointer clone of the pointee.
PType	shareUsage (ValidityChecker &) const
	Other classes that may be able to share the usage of the pointee can do so by calling this method with a ValidityChecker.
	operator const Owned () const
	There is no difference in the layout of a BLink<T> vs that of a BLink<const T>.
bool	isNotNull () const
	Returns true if ptr owned is not null.
bool	isNull () const
	Returns true if ptr owned is null.
size_t	getCountUser () const
	How many owner are sharing ownership of pointer.
size_t	getCountOwned () const
	How many owner are sharing ownership of pointer.
bool	owns (PType rhs) const
	Is rhs same as pointer owned? Returns false if rhs=null.
template<typename O2Type> bool	owns (const BLink< O2Type > &rhs) const
	Is rhs BLink the pointee owned by us? Also returns false if rhs.isNull().
CheckedPtr< OType >	operator() () const
	Use to dereference the Owned pointer.
OType *	ptr () const
	Get the stored pointer directly; get Null if pointer isNull().
bool	operator== (const Owned &rhs) const
	Compare two owners. Equal if both hold same pointer, OR if both hold null pointer.
bool	operator!= (const Owned &rhs) const
	Compare two owners. Two owners are always unequal.
bool	operator< (const Owned &rhs) const
	Compare two owners for sorting.
Protected Types
typedef OType *	PType
	For clarity, pointer type.
Friends
class	Owned
	make inter-type operations possible

---

Member Function Documentation

template<typename OType, OwnershipType oshiptype> template<typename O2Type> MangoPtr::Owned< OType *, oshiptype >::Owned (  std::auto_ptr< O2Type > &    ap )  [inline, explicit]

Take ownership of the pointee owned by a std::auto_ptr. After construction of the Owned, the auto_ptr is invalid. Definition at line 230 of file OwnedPtr.hh. References MangoPtr::isNull(), and MangoPtr::NullPtr.

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

Create an owner from an ownership Original owner looses ownership. Parameters: os  the ownership being transfered Definition at line 243 of file OwnedPtr.hh.

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

Release pointee from ownership by this Owned. All BLink's, and other Owneds if shared ownership, tied to *this will think pointee is no longer valid. This is necessary because the release means the validity can no longer be managed. Attention: Releasing ownership for an Owned<T*, OShared> that has getCountOwned() > 1 releases the ownership for all sharers. This is inevitable and is allowed because releasing from ownership may be a necessary operation. It is perfectly safe even if getCountOwned() > 1, except that you can easily forget that other objects in your program were using the released pointer before release. With proper use of the Owned and BLink, such mistake will be trapped via assertion done automatically by Owner or Vuser's operator() method when dereferencing the (now null) pointer. Definition at line 406 of file OwnedPtr.hh.

template<typename OType, OwnershipType oshiptype> Ownership< OType *, oshiptype > MangoPtr::Owned< OType *, oshiptype >::giveOwnership (    )  [inline]

Give ownership to another object. If the ownership is accepted by that object, the current owner will show isNull() as true. All BLink<T>'s that were tied to this owner will be tied to the new owner. Definition at line 357 of file OwnedPtr.hh.

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

Assume ownership of a pointee. Parameters: p  the pointer to object to own Definition at line 294 of file OwnedPtr.hh.

template<typename OType, OwnershipType oshiptype> template<typename O2Type> void MangoPtr::Owned< OType *, oshiptype >::takeOwnership (  std::auto_ptr< O2Type > &    ap )  [inline]

Transfer ownership from a std::auto_ptr. Parameters: ap  the pointer to object to own Definition at line 307 of file OwnedPtr.hh. References MangoPtr::isNull(), MangoPtr::nullify(), and MangoPtr::Ownership< OType, oshiptype >::owner.

template<typename OType, OwnershipType oshiptype> template<typename O2Type> void MangoPtr::Owned< OType *, oshiptype >::takeOwnership (  Ownership< O2Type, oshiptype >    os )  [inline]

Accept ownership from another Owned. If we already own an object, the object is first destroyed, and any users that were sharing the destroyed pointee know that the pointee is no longer valid. Parameters: os  the carrier of ownership Definition at line 323 of file OwnedPtr.hh.

template<typename OType, OwnershipType oshiptype> OType * MangoPtr::Owned< OType *, oshiptype >::cloneObjNew (    )  const [inline]

Get a dumb pointer clone of the pointee. This is used when copying owners. It can also be used just to get a dumb pointer clone. Since this method can end up being called automatically by compiler when copying Owned, an exception is used instead of assertion since user can often not avoid cloneObj(). Definition at line 381 of file OwnedPtr.hh.

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

Other classes that may be able to share the usage of the pointee can do so by calling this method with a ValidityChecker. The pointer returned is a pointer to the object owned. Note that this method is only to share usage, not ownership. There is no shared ownership. Definition at line 448 of file OwnedPtr.hh.

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

There is no difference in the layout of a BLink<T> vs that of a BLink<const T>. Since converting from a BLink<T> to a const BLink<const T> is often necessary, to mimic the behavior of raw pointers, we have to provide some way of creating a const BLink<const T> from a BLink<T>. This conversion operator is efficient since it just returns a reference to *this, but properly (and portably, ie standardly) cast. Note that converting to a non-const BLink<const T> is not allowed since this would allow (inadvertant) violation of const correctness. This technique is better than the inheritance scheme previously used only because it is more maintainable (and possibly less code is generated). Definition at line 431 of file OwnedPtr.hh. References MangoPtr::isNotNull().

template<typename OType, OwnershipType oshiptype> bool MangoPtr::Owned< OType *, oshiptype >::isNull (    )  const [inline]

Returns true if ptr owned is null. Note: use isNotNull() instead of isNotNull() for better performance. Definition at line 141 of file OwnedPtr.hh.

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

Use to dereference the Owned pointer. I.e., for Owned<Foo*> use owned()->method() where method() is a method of Foo. The distinguishes pure use of pointer, vs dereferencing of pointer, which requires a check that pointer is not null. Definition at line 157 of file OwnedPtr.hh.

---

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

• OwnedPtr.hh

---