GenericElementLinkBase.icc

Go to the documentation of this file.

/*
  Copyright (C) 2002-2024 CERN for the benefit of the ATLAS collaboration
*/
/**
 * @file AthLinks/GenericElementLinkBase.icc
 * @author scott snyder <snyder@bnl.gov>
 * @date Apr, 2014
 * @brief Generic base class for ElementLinks.
 */
 
 
 
namespace SG {
 
 
/**
 * @brief Test the index validity.
 * @returns True if the index is not valid (in default state).
 */
template <class INDEXING_POLICY>
inline
bool
GenericElementLinkBase<INDEXING_POLICY>::isDefaultIndex() const
{
  return ! INDEXING_POLICY::isValid (m_index);
}
 
 
/**
 * @brief Test to see if this link has a cached element pointer.
 */
template <class INDEXING_POLICY>
inline
bool
GenericElementLinkBase<INDEXING_POLICY>::hasCachedElement() const
{
  return m_element.isValid();
}
 
 
/**
 * @brief Test to see if this link is in the default state.
 */
template <class INDEXING_POLICY>
inline
bool
GenericElementLinkBase<INDEXING_POLICY>::isDefault() const
{
  return m_proxy.isDefault() && !hasCachedElement() && isDefaultIndex();
}
 
 
/**
 * @brief Return the index of the link.
 */
template <class INDEXING_POLICY>
inline
typename GenericElementLinkBase<INDEXING_POLICY>::index_type
GenericElementLinkBase<INDEXING_POLICY>::index() const
{
  return INDEXING_POLICY::storedToExternal (m_index);
}
 
 
/**
 * @brief Return the SG key that we reference, as a string.
 *
 * Returns a null string on failure.
 */
template <class INDEXING_POLICY>
inline
const typename GenericElementLinkBase<INDEXING_POLICY>::ID_type&
GenericElementLinkBase<INDEXING_POLICY>::dataID() const
{
  return m_proxy.dataID();
}
 
 
/**
 * @brief Return the SG key that we reference, as a hash.
 *
 * Returns 0 on failure.
 */
template <class INDEXING_POLICY>
inline
typename GenericElementLinkBase<INDEXING_POLICY>::sgkey_t
GenericElementLinkBase<INDEXING_POLICY>::key() const
{
  return m_key;
}
 
 
/**
 * @brief Return the data source for this reference.
 */
template <class INDEXING_POLICY>
inline
IProxyDict*
GenericElementLinkBase<INDEXING_POLICY>::source() const
{
  return m_proxy.source();
}
 
 
/**
 * @brief Return the SG proxy for the container holding this element.
 *
 * If this is a null link, we return 0.
 * If we're directly referencing an object that's not in StoreGate,
 * either return 0 or throw @c ExcPointerNotInSG, depending
 * on @c nothrow.  Otherwise, return the proxy for the object
 * we're referencing.
 */
template <class INDEXING_POLICY>
inline
const SG::DataProxy*
GenericElementLinkBase<INDEXING_POLICY>::proxy() const
{
  return m_proxy.proxy(true);
}
 
 
/**
 * @brief Reset the link to a null state.
 */
template <class INDEXING_POLICY>
inline
void GenericElementLinkBase<INDEXING_POLICY>::reset ()
{
  m_proxy.clear();
  m_key = 0;
  m_element.reset();
  INDEXING_POLICY::reset (m_index);
}
 
 
/**
 * @brief Finish initialization after link has been read.
 * @param sg Associated store.
 *
 * This should be called after a link has been read by root
 * in order to set the proxy pointer.
 * Returns true.
 *
 * If @c sg is 0, then we use the global default store.
 */
template <class INDEXING_POLICY>
inline
bool
GenericElementLinkBase<INDEXING_POLICY>::toTransient (IProxyDict* sg /*= 0*/)
{
  m_proxy.toTransient (m_key, sg);
  m_element.reset();
  return true;
}
 
 
/**
 * @brief Prepare this link for writing.
 *
 * This method should be called before trying to write the link with root.
 * It will make sure the persistent fields of the link are valid.
 * It will also perform remapping if needed.
 *
 * Will return true on success.  Will return false if either the container
 * or the element index has not been specified.  Will throw
 * @c ExcPointerNotInSG if the link is referencing a container that
 * is not in SG.
 */
template <class INDEXING_POLICY>
inline
bool
GenericElementLinkBase<INDEXING_POLICY>::toPersistent()
{
  if (isDefault()) return true;
  if (m_proxy.isDefault() || isDefaultIndex()) return false;
  if (m_proxy.toPersistent (m_key, m_index))
    m_element.reset();
  return true;
}
 
 
/**
 * @brief Adjust for thinning.
 *
 * If this link points to a container that has been thinned,
 * it will be adjusted accordingly.
 *
 * Returns @c true if the link was changed; @c false otherwise.
 */
template <class INDEXING_POLICY>
inline
bool GenericElementLinkBase<INDEXING_POLICY>::thin()
{
  return thin (SG::getThinningCache());
}
 
 
/**
 * @brief Adjust for thinning.
 * @param thinningCache Thinning cache for the current stream
 *                      (may be null).
 *
 * If this link points to a container that has been thinned,
 * it will be adjusted accordingly.
 *
 * Returns @c true if the link was changed; @c false otherwise.
 */
template <class INDEXING_POLICY>
inline
bool GenericElementLinkBase<INDEXING_POLICY>::thin (const SG::ThinningCache* thinningCache)
{
  return thin1 (m_index, thinningCache);
}
 
 
/**
 * @brief Adjust for thinning.
 *
 * If this link points to a container that has been thinned,
 * it will be adjusted accordingly.
 * @param Index of the element.
 * @param thinningCache Thinning cache for the current stream
 *                      (may be null).
 *
 * Returns @c true if the link was changed; @c false otherwise.
 *
 * This overload will be used for the case where thinning is supported:
 * the index can be interconverted with size_t.
 */
template <class INDEXING_POLICY>
template <class INDEX>
requires (std::convertible_to<INDEX, size_t> &&
          std::convertible_to<size_t, INDEX>)
inline
bool GenericElementLinkBase<INDEXING_POLICY>::thin1 (INDEX& persIndex,
                                                     const SG::ThinningCache* thinningCache)
{
  bool ret1 = toPersistent();
  size_t index = static_cast<size_t>(persIndex);
  bool ret = m_proxy.thin (m_key, index, thinningCache);
  if (ret) {
    persIndex = static_cast<stored_index_type>(index);
    m_element.reset();
  }
  return ret1  || ret;
}
 
 
/**
 * @brief Adjust for thinning.
 *
 * If this link points to a container that has been thinned,
 * it will be adjusted accordingly.
 * @param Index of the element.
 * @param thinningCache Thinning cache for the current stream
 *                      (may be null).
 *
 * Returns @c true if the link was changed; @c false otherwise.
 *
 * This overload will be used for the case where thinning is not supported.
 */
template <class INDEXING_POLICY>
template <class INDEX>
requires (!(std::convertible_to<INDEX, size_t> &&
            std::convertible_to<size_t, INDEX>))
inline
bool GenericElementLinkBase<INDEXING_POLICY>::thin1 (INDEX& /*persIndex*/,
                                                     const SG::ThinningCache* /*thinningCache*/)
{
  throwExcBadThinning (this->proxy() ? this->proxy()->clID() : CLID_NULL,
                       this->dataID(), this->key());
}
 
 
/**
 * @brief Default constructor.  Makes a null link.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase()
  : m_key(0),
    m_element()
{
  INDEXING_POLICY::reset (m_index);
}
 
 
/**
 * @brief Construct a link from a string key and an index.
 * @param dataID Key of the object.
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param sg Associated store.
 *
 * If @c sg is 0, we take the global default.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
 (const ID_type& dataID,
  CLID link_clid,
  const index_type& elemID,
  IProxyDict* sg)
   : m_index (static_cast<stored_index_type>(elemID)),
     m_element()
{
  m_key = m_proxy.toIdentifiedObject (dataID, link_clid, sg);
}
 
 
/**
 * @brief Construct a link from a hashed key and an index.
 * @param key Hashed key of the object.
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param sg Associated store.
 *
 * If @c sg is 0, we take the global default.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
 (sgkey_t key,
  CLID link_clid,
  const index_type& elemID,
  IProxyDict* sg)
   : m_key (key),
    m_index (static_cast<stored_index_type>(elemID)),
    m_element()
{
  m_proxy.toIdentifiedObject (key, link_clid, sg);
}
 
 
/**
 * @brief Construct a link from a string key, index, AND pointer to element.
 * @param dataID Key of the object.
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param elt Pointer to the element.
 * @param sg Associated store.
 * 
 * USE CAREFULLY: no coherency checks, we just trust you!
 *
 * If @c sg is 0, we take the global default.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
 (const ID_type& dataID,
  CLID link_clid,
  const index_type& elemID,
  const ElementType& elt,
  IProxyDict* sg)
   : m_index (static_cast<stored_index_type>(elemID)),
     m_element (elt)
{
  m_key = m_proxy.toIdentifiedObject (dataID, link_clid, sg);
}
 
 
/**
 * @brief Construct a link from a hashed key, index, AND pointer to element.
 * @param key Hashed key of the object.
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param elt Pointer to the element.
 * @param sg Associated store.
 * 
 * USE CAREFULLY: no coherency checks, we just trust you!
 *
 * If @c sg is 0, we take the global default.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
 (sgkey_t key,
  CLID link_clid,
  const index_type& elemID,
  const ElementType& elt,
  IProxyDict* sg)
   : m_key (key),
     m_index (static_cast<stored_index_type>(elemID)),
     m_element (elt)
{
  m_proxy.toIdentifiedObject (key, link_clid, sg);
}
 
 
/**
 * @brief Construct a link from an index and pointer to the container.
 * @param obj Pointer to the container (storable).
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param sg Associated store.
 * 
 * If @c sg is 0, we take the global default.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
 (const_pointer_t obj,
  CLID link_clid,
  const index_type& elemID,
  IProxyDict* sg)
   : m_index (static_cast<stored_index_type>(elemID)),
     m_element()
{
  m_key = m_proxy.toStorableObject (obj, link_clid, sg);
}
 
 
/**
 * @brief Construct a link from another link, changing the index.
 * @param other The source link.
 * @param elemID The index for the new link.
 *
 * The index being constructed will reference the same container
 * as @c other, but it will refer to element @c elemID.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
  (const GenericElementLinkBase& other,
   const index_type& elemID)
    : m_key (other.m_key),
      m_index (static_cast<stored_index_type>(elemID)),
      m_proxy (other.m_proxy),
      m_element()
{
}
 
 
/**
 * @brief Construct a link from a DataLink and an index.
 * @param dlink Link to the container.
 * @param index The index of the element within the container.
 */
template <class INDEXING_POLICY>
inline
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
  (const DataLinkBase& dlink,
   const index_type& index)
    : m_key (dlink.key()),
      m_index (static_cast<stored_index_type>(index)),
      m_proxy (dlink.m_proxy),
      m_element()
{
  if (dlink.isDefault()) {
    INDEXING_POLICY::reset (m_index);
  }
}
 
 
/**
 * @brief Constructor from a link referencing a different type.
 * @param other The object from which to copy.
 *
 * @c FROM_TRAITS is the @c ElementLinkTraits class for @c other;
 * @c TO_TRAITS is the traits class for this object.
 * The actual pointer values are not used, just the types are used.
 * Default conversions for the storable pointer (i.e., derived->base)
 * are allowed.
 */
template <class INDEXING_POLICY>
template <class OTHER_INDEXING_POLICY, class FROM_TRAITS, class TO_TRAITS>
GenericElementLinkBase<INDEXING_POLICY>::GenericElementLinkBase
  (const GenericElementLinkBase<OTHER_INDEXING_POLICY>& other,
   FROM_TRAITS*,
   TO_TRAITS*)
  : m_key (other.m_key),
    m_index (other.m_index),
    m_proxy (other.m_proxy,
             (typename FROM_TRAITS::Storable*)0,
             (typename TO_TRAITS::Storable*)0),
    m_element (other.m_element)
{
  // The TRAITS template args are redundant here with the indexing policy args,
  // but we need this signature for the non-templated ElementLinkBase case.
}
 
 
/**
 * @brief Return a pointer to the currently-referenced container object.
 * @param castfn Function to do the cast from data proxy to object.
 *               If 0, use a dynamic cast.
 * @param clid The CLID of the desired object.
 *             This is used to determine how the returned pointer
 *             is to be converted.
 * @param isConst True if the returned object will be treated as const.
 * @return A pointer to an object of the type given by @a clid,
 *         or null on a failure (or if the reference is null).
 */
template <class INDEXING_POLICY>
inline
void* GenericElementLinkBase<INDEXING_POLICY>::storableBase
  (castfn_t* castfn, const CLID& clid, bool isConst) const
{
  return m_proxy.storableBase (castfn, clid, isConst);
}
 
 
/**
 * @brief Set the container referenced by the link to @c data.
 * @param data Pointer to the new container.
 * @param link_clid CLID of the link being set.
 * @param replace True if we can change an existing link.
 * @param sg Associated store.
 * @returns True if the link was changed.
 *
 * If the link is already set, this will return false and leave the
 * link unchanged unless @c replace is set.  The @c replace argument
 * should be set if the element is now in a new storable container;
 * e.g. element ptr has been put in a new view container.
 *
 * If @c sg is 0, then we take the store from whatever the link's currently
 * set to.  If the link has no current store, then we take the global
 * default.
 */
template <class INDEXING_POLICY>
inline
bool GenericElementLinkBase<INDEXING_POLICY>::setStorableObject
   (const_pointer_t data,
    CLID link_clid,
    bool replace,
    IProxyDict* sg)
{
  if (!m_proxy.isDefault()) {
    if (!replace) return false;
    INDEXING_POLICY::reset (m_index);
  }
 
  m_key = m_proxy.toStorableObject (data, link_clid, sg);
  return true;
}
 
 
/**
 * @brief Set the to an element given by index and pointer to container.
 * @param obj Pointer to the container (storable).
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param sg Associated store.
 * @returns True if the link was changed.
 *
 * If the link is already set, this will return false and leave the
 * link unchanged.
 *
 * If @c sg is 0, then we take the store from whatever the link's currently
 * set to.  If the link has no current store, then we take the global
 * default.
 */
template <class INDEXING_POLICY>
inline
bool GenericElementLinkBase<INDEXING_POLICY>::toIndexedElement
   (const_pointer_t obj,
    CLID link_clid,
    const index_type& elemID,
    IProxyDict* sg)
{
  if (m_proxy.isDefault() && isDefaultIndex() && !hasCachedElement()) {
    m_key = m_proxy.toStorableObject (obj, link_clid, sg);
    m_index = static_cast<stored_index_type>(elemID);
    m_element.reset();
    return true;
  }
  return false;
}
 
 
/**
 * @brief Set the link to an element given by string key and index.
 * @param dataID Key of the object.
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param sg Associated store.
 *
 * If @c sg is 0, then we take the store from whatever the link's currently
 * set to.  If the link has no current store, then we take the global
 * default.
 */
template <class INDEXING_POLICY>
inline
void GenericElementLinkBase<INDEXING_POLICY>::resetWithKeyAndIndex
   (const ID_type& dataID,
    CLID link_clid,
    const index_type& elemID, 
    IProxyDict* sg)
{
  m_key = m_proxy.toIdentifiedObject (dataID, link_clid, sg);
  m_index = static_cast<stored_index_type>(elemID);
  m_element.reset();
}
 
 
/**
 * @brief Set the link to an element given by string key and index.
 * @param key Hashed key of the object.
 * @param link_clid CLID of the link being set.
 * @param elemID The index of the element within the container.
 * @param sg Associated store.
 *
 * If @c sg is 0, then we take the store from whatever the link's currently
 * set to.  If the link has no current store, then we take the global
 * default.
 */
template <class INDEXING_POLICY>
inline
void GenericElementLinkBase<INDEXING_POLICY>::resetWithKeyAndIndex
   (sgkey_t key,
    CLID link_clid,
    const index_type& elemID, 
    IProxyDict* sg)
{
  m_key = key;
  m_proxy.toIdentifiedObject (key, link_clid, sg);
  m_index = static_cast<stored_index_type>(elemID);
  m_element.reset();
}
 
 
/**
 * @brief Set the index part of the link.
 * @param index New index value.
 */
template <class INDEXING_POLICY>
inline
void
GenericElementLinkBase<INDEXING_POLICY>::setIndex (const index_type& index)
{
  m_index = static_cast<stored_index_type>(index);
}
 
 
/**
 * @brief Return the stored representation of the link index.
 */
template <class INDEXING_POLICY>
inline
const typename GenericElementLinkBase<INDEXING_POLICY>::stored_index_type&
GenericElementLinkBase<INDEXING_POLICY>::storedIndex() const
{
  return m_index;
}
 
 
/**
 * @brief Set the cached element stored in the link.
 * @param elt New value for the cached element.
 */
template <class INDEXING_POLICY>
inline
void
GenericElementLinkBase<INDEXING_POLICY>::setCachedElement (const ElementType& elt) const
{
  m_element.set (elt);
}
 
 
/**
 * @brief Set the cached element stored in the link.
 * @param elt New value for the cached element.
 */
template <class INDEXING_POLICY>
inline
void
GenericElementLinkBase<INDEXING_POLICY>::storeCachedElement (const ElementType& elt)
{
  m_element.store (elt);
}
 
 
/**
 * @brief Retrieve the cached element from the link.
 * @param elt[out] The cached element.
 * @returns True if an element was cached; false otherwise.
 *
 * @c elt is left unmodified if there is no cached element.
 */
template <class INDEXING_POLICY>
inline
bool
GenericElementLinkBase<INDEXING_POLICY>::getCachedElement (ElementConstPointer& elt) const
{
  if (m_element.isValid()) {
    elt = m_element.ptr();
    return true;
  }
  return false;
}
 
 
/**
 * @brief Return the internal proxy holder object.
 */
template <class INDEXING_POLICY>
inline
const SG::DataProxyHolder&
GenericElementLinkBase<INDEXING_POLICY>::proxyHolder() const
{
  return m_proxy;
}
 
 
} // namespace SG