Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

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

#include <OwnedPtr.hh>

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

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

Collaboration graph
[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:

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

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.

Ownedoperator= (const Owned &rhs)
 Assign from an owned pointer of different type. Only allowed for shared ownership.

template<typename O2Type> Ownedoperator= (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:
Generated on Tue Nov 12 20:44:03 2002 for Mango-ptr Library by doxygen1.2.18