include/GaudiKernel/SmartRef.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2024 CERN for the benefit of the LHCb and ATLAS collaborations *
0003 *                                                                                   *
0004 * This software is distributed under the terms of the Apache version 2 licence,     *
0005 * copied verbatim in the file "LICENSE".                                            *
0006 *                                                                                   *
0007 * In applying this licence, CERN does not waive the privileges and immunities       *
0008 * granted to it by virtue of its status as an Intergovernmental Organization        *
0009 * or submit itself to any jurisdiction.                                             *
0010 \***********************************************************************************/
0011 //  ====================================================================
0012 //  SmartRef.h
0013 //  --------------------------------------------------------------------
0014 //
0015 //  Package   : Kernel
0016 //
0017 //  Author    : Markus Frank
0018 //
0019 //  ====================================================================
0020 #ifndef KERNEL_SMARTREF_H
0021 #define KERNEL_SMARTREF_H 1
0022
0023 // Include files
0024 #include <GaudiKernel/ContainedObject.h>
0025 #include <GaudiKernel/SmartRefBase.h>
0026
0027 #include <typeinfo>
0028
0029 // Forward declarations
0030 template <class TYPE>
0031 class SmartRefArray;
0032 template <class TYPE>
0033 class SmartRefList;
0034 template <class TYPE>
0035 class SmartRefMap;
0036
0037 /** Kernel objects: SmartRef
0038
0039     Description:
0040     The SmartRef class allows transparent handling of object links
0041     within the data store. Links are unloaded a priori and will only be
0042     loaded "on demand", i.e. when dereferenced.
0043
0044     SmartRefs should behave in the same way as normal pointers;
0045     The SmartRef object in fact is a smart pointer construct intercepting
0046     the dereference operators.
0047
0048     When loading, the executed code resides in the non templated base class.
0049     This ensures, that the templated code is minimized and code blow up is
0050     inhibited.
0051
0052     Using SmartRefs StreamBuffers are able to also save the references
0053     on data conversion requests.
0054
0055     Base Class:
0056     SmartRefBase
0057
0058     Dependencies:
0059     <UL>
0060     <LI> Base class:         GaudiKernel/SmartRefBase.h
0061     </UL>
0062
0063     <P> History    :
0064     <PRE>
0065     +---------+----------------------------------------------+--------+
0066     |    Date |                 Comment                      | Who    |
0067     +---------+----------------------------------------------+--------+
0068     | 21/04/99| Initial version.                             | MF     |
0069     | 16/01/04| Move base class into aggregation.            | MF     |
0070     +---------+----------------------------------------------+--------+
0071     </PRE>
0072     Author:  M.Frank
0073     Version: 1.0
0074 */
0075 template <class TYPE>
0076 class SmartRef final {
0077   /// The container must be a friend
0078   friend class SmartRefArray<TYPE>;
0079   friend class SmartRefList<TYPE>;
0080   friend class SmartRefMap<TYPE>;
0081
0082   SmartRefBase m_base;
0083   /// Pointer to target data object
0084   mutable const TYPE* m_target = nullptr;
0085
0086 public:
0087   enum { VALID = StreamBuffer::VALID, INVALID = StreamBuffer::INVALID };
0088   /// Entry type definition
0089   typedef TYPE entry_type;
0090
0091   /// Standard Constructor
0092   SmartRef( const TYPE* pObject = nullptr ) {
0093     m_base.m_hintID = INVALID;
0094     m_base.m_linkID = INVALID;
0095     m_target        = pObject;
0096     _setEnvironment( nullptr, nullptr );
0097   }
0098   /// Copy Constructor
0099   SmartRef( const SmartRef& copy ) {
0100     m_base.m_hintID = copy.m_base.m_hintID;
0101     m_base.m_linkID = copy.m_base.m_linkID;
0102     m_target        = copy.m_target;
0103     _setEnvironment( copy.m_base.m_data, copy.m_base.m_contd );
0104   }
0105   /// Constructor
0106   SmartRef( long hint, long link, const TYPE* obj = nullptr ) {
0107     m_base.m_hintID = hint;
0108     m_base.m_linkID = link;
0109     m_target        = obj;
0110     _setEnvironment( nullptr, nullptr );
0111   }
0112   /// Constructor for references to contained objects passing environment
0113   SmartRef( const ContainedObject* pObj, long hint, long link, const TYPE* obj = nullptr ) {
0114     m_base.m_hintID       = hint;
0115     m_base.m_linkID       = link;
0116     m_target              = obj;
0117     const DataObject* src = ( pObj ? pObj->parent() : nullptr );
0118     _setEnvironment( src, pObj );
0119   }
0120   /// Constructor for references to contained objects passing environment
0121   SmartRef( const DataObject* pObj, long hint, long link, const TYPE* obj = nullptr ) {
0122     m_base.m_hintID = hint;
0123     m_base.m_linkID = link;
0124     m_target        = obj;
0125     _setEnvironment( pObj, nullptr );
0126   }
0127   /// Constructor for references to DataObjects passing environment
0128   SmartRef( const DataObject* pObj, long hint, const TYPE* obj = nullptr ) {
0129     m_base.m_hintID = hint;
0130     m_base.m_linkID = INVALID;
0131     m_target        = obj;
0132     _setEnvironment( pObj, nullptr );
0133   }
0134   /// Check if link should be followed: link must be valid and object not yet loaded
0135   bool shouldFollowLink( const DataObject* ) const { return !m_target && m_base.m_hintID != INVALID; }
0136   /// Check if link should be followed: link must be valid and object not yet loaded
0137   bool shouldFollowLink( const ContainedObject* ) const {
0138     return !m_target && m_base.m_hintID != INVALID && m_base.m_linkID != INVALID;
0139   }
0140   /// Access hint id:
0141   long hintID() const { return m_base.m_hintID; }
0142   /// Access link id:
0143   long linkID() const { return m_base.m_linkID; }
0144   /// Setup smart reference when reading. Must be allowed from external sources.
0145   void set( DataObject* pObj, long hint_id, long link_id ) { m_base.set( pObj, hint_id, link_id ); }
0146   /// Access to embedded type
0147   const std::type_info* type() const { return &typeid( TYPE ); }
0148   /// Access to raw data pointer
0149   TYPE*       data() { return const_cast<TYPE*>( m_target ); }
0150   const TYPE* data() const { return m_target; }
0151   /// Access to the object
0152   const TYPE* target() const {
0153     if ( !m_target ) { m_target = dynamic_cast<const TYPE*>( m_base.accessData( m_target ) ); }
0154     return m_target;
0155   }
0156   /// Access to the object
0157   TYPE* target() {
0158     if ( !m_target ) { m_target = dynamic_cast<const TYPE*>( m_base.accessData( m_target ) ); }
0159     return const_cast<TYPE*>( m_target );
0160   }
0161   /// Return the path of the linked object inside the data store.
0162   const std::string& path() const { return m_base.path(); }
0163   /// Equality operator
0164   bool operator==( const SmartRef<TYPE>& c ) const {
0165     if ( m_target && c.m_target ) return m_target == c.m_target;
0166     if ( !m_target && !c.m_target ) return m_base.isEqual( m_target, c.m_base );
0167     if ( m_target && !c.m_target ) return m_base.isEqualEx( m_target, c.m_base );
0168     if ( !m_target && c.m_target ) return c.m_base.isEqualEx( c.m_target, m_base );
0169     return false;
0170   }
0171   friend bool operator==( const SmartRef<TYPE>& ref, std::nullptr_t ) { return ref.target() == nullptr; }
0172
0173   /// Friend helper to check for object existence (will load object)
0174   friend bool operator==( std::nullptr_t, const SmartRef<TYPE>& ref ) { return ref.target() == nullptr; }
0175   /// NON-Equality operator
0176   bool operator!=( const SmartRef<TYPE>& c ) const { return !( this->operator==( c ) ); }
0177
0178   friend bool operator!=( const SmartRef<TYPE>& ref, std::nullptr_t ) { return ref.target() != nullptr; }
0179
0180   /// Friend helper to check for object existence (will load object)
0181   friend bool operator!=( std::nullptr_t, const SmartRef<TYPE>& ref ) { return ref.target() != nullptr; }
0182
0183   /// explicit conversion to bool to check for object existence (will load object)
0184   explicit operator bool() const { return target() != nullptr; }
0185
0186   /// Set the environment (CONST)
0187   const SmartRef<TYPE>& _setEnvironment( const DataObject* pObj, const ContainedObject* pContd ) const {
0188     m_base.m_data  = pObj;
0189     m_base.m_contd = pContd;
0190     m_base.setObjectType( data() );
0191     return *this;
0192   }
0193   /// Set the environment (CONST)
0194   SmartRef<TYPE>& _setEnvironment( const DataObject* pObj, const ContainedObject* pContd ) {
0195     m_base.m_data  = pObj;
0196     m_base.m_contd = pContd;
0197     m_base.setObjectType( data() );
0198     return *this;
0199   }
0200   /// operator(): assigns parent object for serialisation
0201   SmartRef<TYPE>& operator()( ContainedObject* pObj ) {
0202     const DataObject* src = ( pObj ? pObj->parent() : nullptr );
0203     return _setEnvironment( src, pObj );
0204   }
0205   /// operator() const: assigns parent object for serialisation
0206   const SmartRef<TYPE>& operator()( const ContainedObject* pObj ) const {
0207     const DataObject* src = ( pObj ? pObj->parent() : nullptr );
0208     return _setEnvironment( src, pObj );
0209   }
0210   /// operator(): assigns parent object for serialisation
0211   SmartRef<TYPE>& operator()( DataObject* pObj ) { return _setEnvironment( pObj, nullptr ); }
0212   /// operator() const: assigns parent object for serialisation
0213   const SmartRef<TYPE>& operator()( const DataObject* pObj ) const { return _setEnvironment( pObj, nullptr ); }
0214   /// Assignment
0215   SmartRef<TYPE>& operator=( const SmartRef<TYPE>& c ) {
0216     m_target        = c.m_target;
0217     m_base.m_hintID = c.m_base.m_hintID;
0218     m_base.m_linkID = c.m_base.m_linkID;
0219     return _setEnvironment( c.m_base.m_data, c.m_base.m_contd );
0220   }
0221   /// Assignment
0222   SmartRef<TYPE>& operator=( const TYPE* pObject ) {
0223     m_target        = pObject;
0224     m_base.m_hintID = INVALID;
0225     m_base.m_linkID = INVALID;
0226     return *this;
0227   }
0228   /// Dereference operator
0229   TYPE& operator*() { return *SmartRef<TYPE>::target(); }
0230   /// Dereference operator
0231   const TYPE& operator*() const { return *SmartRef<TYPE>::target(); }
0232   /// Dereference operator
0233   TYPE* operator->() { return SmartRef<TYPE>::target(); }
0234   /// Dereference operator to const object
0235   const TYPE* operator->() const { return SmartRef<TYPE>::target(); }
0236   /// Implicit type conversion to const object
0237   operator const TYPE*() const { return SmartRef<TYPE>::target(); }
0238   /// Implicit type conversion
0239   operator TYPE*() { return SmartRef<TYPE>::target(); }
0240   /// Write the reference to the stream buffer (needed due to stupid G++ compiler)
0241   StreamBuffer& writeRef( StreamBuffer& s ) const {
0242     m_base.writeObject( m_target, s );
0243     return s;
0244   }
0245   /// Read the reference from the stream buffer (needed due to stupid G++ compiler)
0246   StreamBuffer& readRef( StreamBuffer& s ) {
0247     m_target = dynamic_cast<const TYPE*>( m_base.readObject( m_target, s ) );
0248     return s;
0249   }
0250   /// Output Streamer operator
0251   // MCl: it is "_s" instead of the most common "s" to avoid a fake icc remark #1599
0252   friend StreamBuffer& operator<<( StreamBuffer& _s, const SmartRef<TYPE>& ptr ) { return ptr.writeRef( _s ); }
0253   /// Input Streamer operator
0254   // MCl: it is "_s" instead of the most common "s" to avoid a fake icc remark #1599
0255   friend StreamBuffer& operator>>( StreamBuffer& _s, SmartRef<TYPE>& ptr ) { return ptr.readRef( _s ); }
0256 };
0257
0258 #endif // KERNEL_SMARTREF_H