On the Use of Reference Semantics in HepTuple


  At the time the Fermi Physics Class Library Task Force undertook to
enhance the capabilities of the HepTuple package, pointer semantics were
in use throughout the package.	For example, creating a histogram (via
the file manager) returned, to the user, a pointer to the newly-created
histogram.  This pointer was subsequently employed to fill the histogram,
write the histogram, and, in general, for all operations defined on this
object.  (All remarks herein apply equally to histograms and ntuples.)

  While this approach was certainly effective in manipulating histograms,
it posed a risk.  In particular, a naive or unwary user might very easily
delete the histogram object.  While this posed little or no problem in
the package as inherited by FPCLTF, it is important in the current version
to allow the file manager object to complete the histogram's life cycle.
Indeed, it would be disastrous, under the current scheme, for a histogram
to disappear from memory without the manager's knowledge:  in order to
enable retrieval of existing histograms from a previously-written file,
while simultaneously enforcing uniqueness of histograms' titles and id
numbers, the manager tracks all histogram objects, whether in active
use or not.

  The FPCLTF considered several options to address this problem.  After
considerable deliberation, we opted for a small change to reference
semantics in place of the pointer semantics that permitted the unfriendly
deletion.

  Thus, the file manager now returns a reference to a new or newly-
retrieved histogram.  The user may fill, write, etc., this histogram
using dot notation rather than arrow notation.  This notation is
intended to convey that memory management for the histogram object is
not the the responsibility of user code.  In particular, the user need
not delete the histogram object.

  This means, of course, that existing HepTuple users will need to update
their programs to take advantage of the change.  We had previously
agreed, in conversation and email with Babar's Bob Jacobson, that it
would be acceptable to change the name of the manager's factory routine;
thus users of the revised HepTuple package need to use the new name.
If it is too much trouble to propagate the reference semantics throughout
existing code, a user may simply insert an & in front of this new name,
thus converting the reference into a pointer.

  Clearly, a user who obtains a pointer to a histogram in this way can
still delete the histogram; however, the fact that the user is explictly
taking the address (instead of being handed an address), should strongly
suggest that the histogram object is not the result of the user's dynamic
allocation and therefore the user has no responsibility to delete the
histogram object.

  In summary, we have the following:

	// [1] Original (pointer-based) usage:
	  HepFileManager * m = new HepHBookFileManager( /*...*/ );
	  Hist1D * h = m->newHist1D( /*...*/ );
	// Warning: do NOT delete h

	// [2] Recommended (new, reference-based) usage:
	  HepHBookFileManager m( /*...*/ );
	  Hist1D & h = m.hist1D( /*...*/ );

	// [3] Acceptable, but deprecated, usage:
	  HepHBookFileManager m( /*...*/ );
	  Hist1D * h = & m.hist1D( /*...*/ );
	// Warning: do NOT delete h

  To improve memory management, users are encouraged, in all cases, to
tell the manager when they have no further need for a given histogram.
This may be accomplished via either of the following two methods (using
the above recommended notation [2]):

	h.release();
	m.release( h );

In either case, it is disastrous to continue using h after having
release()'d it.