---

When to use what classes

• MangoPtr::Owned<Container>:
  • Use as a class data member or local variable:
    • To automate call to 'delete' for each element of container
    • To make clear which class/instance owns container
    • To help with exception-safety
    • To prevent inadvertent shallow copying of list when class member

• MangoPtr::Owned<T*>:
  • Use as a class data member or local variable:
    • Instead of std::auto_ptr
    • To automate call to 'delete'
    • To make clear which class/instance owns pointee
    • To help with exception-safety
    • To prevent inadvertent shallow copying of pointer when class member
    • In debug mode, to automatically validate pointee before dereferencing
  • Not suitable for STL containers (use Owned<T, OShared> instead)

• MangoPtr::Owned<T*, OShared>:
  • Use as a class data member only if design requires shared ownership between several class instances:
    • To make sure resource stays "alive" until no longer needed
    • To make clear which group of classes/instances own an object, vs simply use an object
    • In debug mode, to automatically validate pointee before dereferencing, useful when release() may have been used
  • Use as element type for STL container that owns the pointers, since STL uses value semantics (not applicable to strict ownership), and:
    • only use BLink's tie to the elements, outside container, to make the container a strict owner
    • also use Owned<T, OShared> outside of container, to make container share ownership with other classes; elements from list are deleted only when last shared owner is destroyed
  • Should never have to use as local variable

• MangoPtr::Ownership<T>:
  • To make clear that one owned pointer is being transfered to another owned pointer
  • To implement explicit move semantics
  • To make clear that only the ownership aspect of an owned pointer is going to be affected

• MangoPtr::BLink<T>: Use as a class data member, local variable, or STL container element:
  • To make clear that the object is only being used, not owned, by class, scope, or container, i.e. to clearly state that pointee lifetime is governed by another scope
  • To allow validation of pointee based lifetime of an Owned or BLinkable<>
  • In debug mode, to automatically validate pointee before dereferencing
  • To clearly state that pointee is owned by someone else, and not by user of BLink
  • To clearly state that pointee will be shallow-copied

• Owned<T*>:: operator() and BLink<T>:: operator(): Use to get pointer stored in the object:
  • In debug mode, helps trap dangling pointers (if the returned value is dereferenced directly)
  • In normal mode, same as having pointer directly

• BLinkable<>:
  • As a base class for a class that wants to give out BLink<T> that point to itself.

---