/*****************************************************************************
 * $LastChangedDate: 2010-05-25 21:26:05 -0400 (Tue, 25 May 2010) $
 * @file
 * @author  Jim E. Brooks  http://www.palomino3d.org
 * @brief   Template class to shield a pointer from deletion.
 *//*
 * LEGAL:   COPYRIGHT (C) 2006 JIM E. BROOKS
 *          THIS SOURCE CODE IS RELEASED UNDER THE TERMS
 *          OF THE GNU GENERAL PUBLIC LICENSE VERSION 2 (GPL 2).
 *****************************************************************************/

////////////////////////////////////////////////////////////////////////////////
/// @class base::SafePtr
/// @brief Template class to prevent deleting an object by its pointer (see base/safe_ptr_doc.hh).
////////////////////////////////////////////////////////////////////////////////

//------------------------------------------------------------------------------
// Template class to shield an object being deleting by its pointer
// and to help the object's creator to retain ownership.
// It prevents the pitfall of passing pointers around
// and some subroutine deletes it by mistake.
//
// Examples:
// ---------
// SafePtr<Object> object = new Object;
// SafePtr<const Object> object = new Object;
//
// Remember:
// ---------
// - Return "const SafePtr<>" instead of just "SafePtr<>" (covers pitfall).
// - Passing "const SafePtr<>" is recommended.
// - Pass SafePtr<> by value (by reference is actually slower)
// - Be careful using SafePtr<> in existing code that casts pointers.
//
// WARNING:
// --------
// SafePtr<> suffers from the assignment-to-temporary pitfall.
// The cure is const: functions should return "const SafePtr<>", not just "SafePtr<>".
// For example, changing mData to private and interfacing it with
// a getter method opens the pitfall:
//     SafePtr<Object> GetObject(void);
//     mObject = obj;      // old code
//     GetObject() = obj;  // new code: oops! A temporary Ptr<> object was assigned!
//
// Design notes:
// -------------
// Omitted is a conversion operator from SafePtr<T> to T* as that
// would defeat the purpose by making "delete ptr" compile.
// operator bool() is implicitly defined for actual pointers but omitted for SafePtr<>,
// so writing explicitly writing NULL is required: "if (ptr != NULL)"
// and the requirement helps finding/eliminating NULL states.
//------------------------------------------------------------------------------
