Project

General

Profile

History

A note on the behavior of art::Ptr

The class template Ptr<T>, which being a variety of "smart pointer", has more states than is common for pointer-like types. This is a result of the fact that it represents a persistent pointer to an object contained within a "container" in an (e.g.) Event. To understand the available states, it is best to think of the Ptr<T> object as containing:

  1. an identifier of the "container" into which it refers [this is the role of the ProductID], and
  2. an identifier of which object of type T in that "container" is referenced by the pointer [this is the role of the "key"].

The Ptr<T> class template also has transient data members which can be ignored for this discussion.

The permissible states of instances of Ptr<T> are:

  1. Default constructed: No valid ProductID, no valid offset. Such a Ptr does not reference any product.
  2. Constructed with a valid ProductID, but with no valid key. Such a Ptr is intended to be used as a "null pointer", indicating that there was no object in the collection for this Ptr to reference.
  3. Constructed with a valid ProductID and a valid key. Such a Ptr references the object of type T identified by the key in the "container" with the given ProductID.

An instance of Ptr<T> that is in state 3 might be in a state that can be dereferenced, but it might not be. If the product which is "pointed into" by the pointer is not present in the data (perhaps because one is reading a file to which that product was not written), the Ptr<T> can not be dereferenced.

The above information, including the results of various different ways to interrogate the state, can be summarized in the table below:

Valid ProductID Valid offset isNull() isAvailable() explicit operator bool() Comment
Y Y F T/F T/F Variable answers depend on whether product is resolvable.
Y N T T/F F Variable answer depends on whether product is resolvable.
N N F F F Only possible through default constructor.

Note that the unlisted combination with an invalid ProductID but valid offset is not a possible state of Ptr. In the event that someone calls the constructor of Ptr taking a Handle argument where the Handle does not have a valid ProductID, an exception will be thrown regardless of the validity of the provided offset.