---

MangoPtr::BLink< OType > Class Template Reference

#include <BLink.hh>

Collaboration diagram for MangoPtr::BLink< OType >:

[legend]List of all members.

---

Detailed Description

template<typename OType>
class MangoPtr::BLink< OType >

A "Better Link", a kind of pointer that can be validated.

A BLink can be linked to owned containers, owned pointers, and objects that inherit from BLinkable<ForOwnedBy::This>. When the linkee (what is being linked to) is destroyed, it sets a flag that the BLink can check, that tells it that the linkee no longer exists. You can therefore always test whether resources linked to still exist or not.

Using a BLink<T> is simple: tie it to an Owned<DT>, Owned<DT*>, BLinkable<> or another BLink<DT> (DT is T or a class derived from T) when you construct the BLink or via a call to tieTo() after construction. Then do usual pointer-like operations (dereference etc), and call isNull() or isNotNull() to test whether or not the pointee still exists. Tying a BLink to another BLink is like tying it to the object that the other BLink is tied to. All BLinks tied to the same object can tell if the resource still exists or not.

The op= operator only accepts another BLink since this is the only use that makes sense. It is equivalent to tying a BLink to the same Owned or BLinkable<> as the BLink on the RHS.

There is nothing to prevent you from tying a BLink to an Owned that doesn't own anything (because Owned was not initialized, or what it owned was discarded or released()).

Here is an example of usage. You can find another in the MangoPtr::Owned<T> docs:

    class Window; // some sort of window class
    class Foo {...};
    void Foo::setWindow(const BLink<Window>& win_arg)
    {
        win = win_arg;
        // later, foo can check win.isNotNull() to see if 
        // the win window still exists
    }
    int main() 
    {
        Window mainApp;
        mainApp.createWindows();
        Foo foo;
        // assume mainApp.getRootWindow() returns a BLink
        foo.setWindow( mainApp.getRootWindow() );
    }

The different transfer of ownership for owned containers vs owned pointers has an impact on BLinks.

• A BLink that is tied to an owned container stays linked to that container even if the ownership of the container changes hands. This is because transfering such ownership is equivalent, for owned containers, to moving the contents of one container to the other. This means that if owned container A takes ownership of owned container B, B ends up with an empty container, and A with B's former content. A BLink that was tied to A now sees the new content of A, and a BLink that was tied to B sees that B is an empty container. The BLink for a container is invalidated only when the container is actually destroyed. This behavior is the same as for dumb pointers (or references) to containers.
• On the other hand, a BLink that is tied to an owned pointer is always linked to the owner of the pointer, rather than the pointer itself. This is because the raw pointer itself is moved to the different owner, so the BLink becomes tied to the new owner. A container is not moved, only its contents are moved.

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

        void func(const BLink<const T>&); // will only use pointer
        void gunc(BLink<const T>&); // will likely change sptrship
        //...
        BLink<T> sptr;
        BLink<const T> sptrConst;
        func(sptrConst); // ok
        gunc(sptrConst); // ok
        func(sptr);      // ok
        gunc(sptr);      // compile error since can't convert

See the note in the MangoPtr::Owned<T*> docs regarding the relationship between BLink<T> and BLink<const T> in terms of implementation.

Attention:

All methods not documented here are documented in BLink<const T>, for reasons that are too involved to explain here (but are related to a bug in the documentation generation program, doxygen, used to extract the docs from the files).

Todo:

add std::swap specialization

Author:

Oliver Schoenborn

Since:

Mar 2002

Definition at line 45 of file BLink.hh.

Public Types
typedef OType	ObjectType
	Class of object held, a la auto_ptr.
Public Methods
Constructors
	BLink () throw ()
	Empty BLink. Can't be used until tied to an owner.
	BLink (const BLink &)
	Empty BLink. Can't be used until tied to an owner.
template<typename OType2>	BLink (const BLink< OType2 > &)
	Tie a user to same owner as rhs is tied to.
	BLink (OType &)
	Create from an object that derives publically from BLinkable<>.
template<typename OType2, OwnershipType oshiptype>	BLink (const Owned< OType2, oshiptype > &)
	Create from an Owned.
Mutators
template<typename OType2, OwnershipType oshiptype> void	tieTo (const Owned< OType2, oshiptype > &)
	Tie this BLink to an Owned.
void	tieTo (OType &)
	Tie to an object.
BLink &	operator= (const BLink &)
	Make this BLink use the same pointee as rhs.
template<typename OType2> BLink &	operator= (const BLink< OType2 > &)
	Same as operator=(const BLink &) but for BLink of different type.
void	swap (BLink &) throw ()
	Swap two BLink's.
void	reset ()
	reset to default-constructed state
Query/Utility
bool	isNotNull () const throw ()
	True only if pointee still alive.
bool	isNull () const throw ()
	Return true if resource linked to no longer exists.
PType	cloneObjNew () const
	Clone the pointee using new.
Operators
	operator const BLink () const
	There is no difference in the layout of a BLink<T> vs that of a BLink<const T>.
template<typename OType2> bool	operator< (const BLink< OType2 > &) const throw ()
	For sorted STL containers (amongst other things).
template<typename OType2> bool	operator== (const BLink< OType2 > &) const throw ()
	Compare to another BLink.
template<typename OType2> bool	operator!= (const BLink< OType2 > &) const throw ()
	Compare to another BLink.
CheckedPtr< OType >	operator() () const
	Use to dereference the BLink.
OType *	ptr () const
	Use this to get pointer to object blinked-to.
Friends
class	BLink
	make conversion of OType possible

---

Constructor & Destructor Documentation

template<typename OType> MangoPtr::BLink< OType >::BLink (  OType &    oobj )  [inline]

Create from an object that derives publically from BLinkable<>. The validity of the BLink will be tied to the lifetime of oobj. Definition at line 175 of file BLink.hh.

---

Member Function Documentation

template<typename OType> template<typename OType2, OwnershipType oshiptype> void MangoPtr::BLink< OType >::tieTo (  const Owned< OType2, oshiptype > &    owner )  [inline]

Tie this BLink to an Owned. This allows the caller to use the pointee managed by the owner. BLink will be invalid if owner is invalid. Definition at line 238 of file BLink.hh. References MangoPtr::SharedValidity::isShared(), and MangoPtr::SharedValidity::isValid().

template<typename OType> void MangoPtr::BLink< OType >::tieTo (  OType &    blinkable )  [inline]

Tie to an object. Class OType must inherit from BLinkable<ForOwnedBy::This>. Definition at line 252 of file BLink.hh.

template<typename OType> BLink< OType > & MangoPtr::BLink< OType >::operator= (  const BLink< OType > &    rhs )  [inline]

Make this BLink use the same pointee as rhs. This is equivalent to calling tieTo() on the owner of rhs (which is not always available at the point of call). Definition at line 203 of file BLink.hh. References MangoPtr::SharedValidity::isShared(), MangoPtr::SharedValidity::isValid(), MangoPtr::BLink< OType >::optr, and MangoPtr::BLink< OType >::validator.

template<typename OType> OType * MangoPtr::BLink< OType >::cloneObjNew (    )  const [inline]

Clone the pointee using new. This is just a convenience method that does the call to new for you, but is otherwise pure gravy. If you object requires a special call, do instead something like: // assume an owner exists somewhere BLink<T> blink( owner ); Owned<T*> newOwner( blink()->clone() ); // newOwner now has a clone of the original pointee Definition at line 342 of file BLink.hh.

template<typename OType> MangoPtr::BLink< OType >::operator const BLink< const OType > & (    )  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 285 of file BLink.hh.

template<typename OType> template<typename OType2> bool MangoPtr::BLink< OType >::operator== (  const BLink< OType2 > &    rhs )  const throw () [inline]

Compare to another BLink. Same iff the pointers being stored are same. Definition at line 310 of file BLink.hh.

template<typename OType> template<typename OType2> bool MangoPtr::BLink< OType >::operator!= (  const BLink< OType2 > &    rhs )  const throw () [inline]

Compare to another BLink. Different iff the pointers being stored are different. Definition at line 323 of file BLink.hh.

template<typename OType> CheckedPtr<OType> MangoPtr::BLink< OType >::operator() (    )  const [inline]

Use to dereference the BLink. I.e., for BLink<Foo> use blink()->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 127 of file BLink.hh.

---

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

• BLink.hh

---