---

Quick Start

All classes are in the MangoPtr namespace. A default namespace alias called Ptr is defined for you. See MangoPtrNamespaceAlias.hh for details.

Summary of classes and functions available

See next section for more details.

Normal use (in MangoPtr namespace):

• Owned<Container>: owned container of pointers
• Owned<Container&, OShared>: owned container of pointers, where container exists elsewhere
• Owned<ObjectType*>: owned pointer, strict ownership
• Owned<ObjectType*, OShared>: owned pointer, shared ownership
• BLink<ObjectType>: better link, ie. where object linked-to is either an Owned container or pointer, or an object derived from BLinkable<>.
• Ownership<ObjectType>: transaction objet to transfer ownership from one owned pointer to another
• BLinkable<>: subclass is an object that has a shared validity flag such that the object can be given to BLink<objectClass> to create a "better link" to the object, ie. a link that can be tested for validity.

Advanced use (in MangoPtr namespace):

• CntrCloner<Container>: may be specialized if you want to use Owned<Container>cloneObjNew() AND your container element type must be cloned with something else than new()
• CntrCleaner<Container>: may be specialized if the container does not have an iterator, otherwise necessary for cleanup
• CheckedPtr<ObjectType>: proxy for a pointer, with assertion before dereference

Other (in global namespace):

• isNull(PointerType), isNotNull(PointerType), nullify(PointerType): IMHO better than using NULL

Brief descriptions for normal use

The classes described briefly in the previous section for "normal" use are described in more detail here. The header file(s) needed to use the class in your code is listed. Header files that have "FWD" at the end of their name give the forward declaration of the associated class, useful to minimize the coupling between your header files.

Owned<Container>

• Header files: OwnedCntr.hh, OwnedFWD.hh
• Strict owned container of pointers. When the container goes out of scope, it automatically calls delete on all its elements. More complicated containers are possible, as long as a pointer type occurs somewhere in the type declaration (e.g. Owned<std::list<std::vector<T*> > >).
• Example 1: A class Bar has an owned list of Beer* so that when Bar objects go out of scope, the Beer's are automatically destroyed. Note that getBeerBox() returns a reference to the inner container, not to the owned container, since the fact that it is owned is an implementaiton detail:

      typedef std::list<Beer*> Beers;
      class Bar {
          private:
              Owned<Beers> olist; // owned list
          public:
              Bar() {... populate owned list ...}
              const Beers& getBeerBox() const {return olist.cntr(); }
      };
  

• Example 2: A BeerBoxUser class can always know when the Bar has been destroyed, assuming the Bar::getBeerBox has been replaced:

      class Bar {
          // ...
              BLink<Beers> getBeerBox() const { return olist; }
      };
      class BeerBoxUser 
      {
          BLink<Beers> beerBox;
          public:
              BeerBoxUser(const Bar& bar): beerBox( bar.getBeerBox() ) {}
              int countBeers() const 
              {
                  // the Bar may no longer even exist!
                  if (beerBox.isNull()) return 0;
                  // ok, there's a bar, so count the beers
                  return beerBox()->size();
              }
      };
  

Owned<Container&, OShared>

• Header files: OwnedCntrShared.hh, OwnedFWD.hh
• A shared container of pointers simply keeps a reference to a container stored somewhere else, and when the Owned is destroyed, it cleans up the container of pointers by calling delete on each element. Always favor using Owned<Container> and use the shared version just as a last resort.
• Example: a function that must fill a container with dynamically allocated objects, and the fill should be an atomic operation (list properly filled, or nothing added at all):

      typedef std::list<Beer*> Beers;
      void fillList(Beers& beers) 
      {
          assert(beers.empty());
          Owned<Beers> obeers;
          for (int i=0; i<5; i++) 
              // if new or constructor throws, Owned will 
              // delete all Beer
              obeers()->push_back(new Beer);
      }
      // as mentioned, I have a hard time seeing how you could ever really
      // want to use this class, but in case there are some good idioms
      // that I haven't thought of, it is provided too.
  

Owned<PointerType>

• Header files: OwnedPtr.hh, OwnedFWD.hh
• Strictly owned pointer to an object allocated from dynamic memory via new(). Like std::auto_ptr<T>, it deletes the resource owned when it goes out of scope, but unlike it, it
  • cannot be copied (use cloneObjNew() method instead, or equivalent)
  • makes ownership transfer explicit
  • collaborates with BLink
• Example:

      Owned<Foo*> foo(new Foo);
      foo()->someFooMethod(); // could throw, safe due to Owned
      // assume void someFunc(const Owned<const Foo*>&):
      someFunc(foo);
  

• More Examples: See Idiomatic examples

Owned<PointerType, OShared>:

• Header files: OwnedPtrShared.hh, OwnedFWD.hh
• Shared owned pointer of an object allocated from dynamic memory via new(). Always prefer "Owned<P*>" (ie strict ownership) to "Owned<P*, OShared>" (ie shared ownership), and "Owned<Container<P*> >" to "Container<Owned<T*, OShared> >". Unlike std::auto_ptr<T>, it:
  • deletes the resource owned when it goes out of scope, only if it is the last owner to be owning it;
  • can only be copied (supports proper copy semantics rather than move semantics)
  • makes ownership transfer explicit
  • collaborates with BLink
• Example: replace Owned<P*> with Owned<P*, OShared> in examples of Owned<P*>. Note that we discourage the use of Owned<P*, OShared> as it encourage sloppy and non-deterministic management of resources, and easily leads to implicit and unintended shallow copying (not the case with strict ownership), in addition to cyclical references.

BLink<ObjectType>

• Header files: BLink.hh, BLinkFWD.hh
• Better link, a pointer that is tied to an owned object or to a ValidityOwner. Has NO concept of ownership, merely usage of the object linked to. You can always test the validity (i.e. existence) of the pointee object by calling the isNull() or isNotNull() methods.
• Example 1:

      class Bar {
          Owned<Foo*> ofoo; 
          public:
              BLink<Foo> getFooObj() const {return ofoo;}
      };
      // ...
      BLink<const Foo> foo( getFooObj() );
      if (foo.isNull()) // no foo object exists; do something special
          ....;
      else // do something on foo object
          foo->callConstMethod();
  

• Example 2: See example 2 of Owned<Container> above
• Example 3: See the example that uses ValidityOwner for BLink to one-self: Use callback idiom

Ownership<ObjectType>

• Header files: Ownership.hh, OwnershipFWD.hh
• Transaction object created when one owned pointer gives its ownership to another. This makes explicit the action of transfering ownership and forces both the giver and taker to be explicitly mentioned.
• Example: as in FIFO Factory pattern

      // assume Bar is a class that has method:
      void Bar::getObj(Owner<Foo*>& newOwner) {
          newOwner.takeOwnership( oldOwner.giveOwnership());
      }
  

• Example 2: see Factory pattern in Another FIFO Factory pattern, where following technique used:

      // assume Bar is a class that has method:
      Ownership<Foo*> Factory::adoptFooObj() {
          return oldOwner.giveOwnership();
      }
  

BLinkable<>

• Header files: BLinkable.hh, BLinkableFWD.hh
• Base class for objects which must produce BLinks to themselves, e.g. for registering self to an observer or event generator.
• Example: See Use callback idiom

---