AuxVectorData.icc

Go to the documentation of this file.

// Dear emacs, this is -*- c++ -*-
/*
  Copyright (C) 2002-2024 CERN for the benefit of the ATLAS collaboration
*/
/**
 * @file AthContainers/AuxVectorData.icc
 * @author scott snyder <snyder@bnl.gov>
 * @date Sep, 2013
 * @brief Manage lookup of vectors of auxiliary data.
 */
 
 
#include "AthContainersInterfaces/IAuxStore.h"
#include "AthContainersInterfaces/IConstAuxStore.h"
#include "AthContainers/tools/likely.h"
#include "AthContainers/tools/assume.h"
 
 
namespace SG {
 
 
/**
 * @brief Return the current store, as a const interface.
 *
 * This will be non-zero if either a const or non-const store
 * is associated with this object.
 */
inline
const SG::IConstAuxStore* AuxVectorData::getConstStore() const
{
   if( m_constStore ) {
      return m_constStore;
   }
   if( !m_constStoreLink.isDefault() ) {
      return m_constStoreLink.cptr();
   }
   return 0;
}
 
 
/**
 * @brief Return the data link to the current store, as a const interface.
 *
 * This is set by persistency when reading an object, but it may
 * be overridden by setting the store pointer directly.
 */
inline
const DataLink<SG::IConstAuxStore> AuxVectorData::getConstStoreLink() const
{
  return m_constStoreLink;
}
 
 
/**
 * @brief Return the current store, as a non-const interface.
 *
 * This will be non-zero if a non-const store is associated with this object.
 */
inline
SG::IAuxStore* AuxVectorData::getStore()
{
  return m_store;
}
 
 
/**
 * @brief Return the current store, as a non-const interface.
 *
 * This will be non-zero if a non-const store is associated with this object.
 */
inline
const SG::IAuxStore* AuxVectorData::getStore() const
{
  return m_store;
}
 
 
/**
 * @brief Return true if this object has an associated store.
 */
inline
bool AuxVectorData::hasStore() const
{
  return ( getConstStore() != 0 );
}
 
 
/**
 * @brief Return true if this object has an associated non-const store.
 */
inline
bool AuxVectorData::hasNonConstStore() const
{
  return m_store != 0;
}
 
 
/**
 * @brief Set the store associated with this object.
 * @param store The new store.
 *
 * This will set both the const and non-const store pointers, and also
 * clear the cache.
 * This is the same as setStore() above with the same signature.
 * It exists so that it can be called from python; pyroot would not
 * be able to call the non-const overload of setStore due to its
 * simplistic overload resolution.
 */
inline
void AuxVectorData::setNonConstStore (SG::IAuxStore* store)
{
  setStore (store);
}
 
 
/**
 * @brief Test to see if a variable exists in the store.
 * @param id The variable to test.
 */
inline
bool AuxVectorData::isAvailable (auxid_t id) const
{
  // First check to see if this variable is present in the cache.
  if (m_constCache.cachePtr (id)) return true;
  return isAvailableOol (id);
}
 
 
/**
 * @brief Test to see if a variable is available for writing.
 * @param id The variable to test.
 */
inline
bool AuxVectorData::isAvailableWritable (auxid_t id)
{
  // First check to see if this variable is present in the cache.
  if (m_cache.cachePtr (id)) return true;
  return isAvailableWritableOol (id);
}
 
 
/**
 * @brief Test to see if a variable is available for writing as a decoration.
 * @param id The variable to test.
 */
inline
bool AuxVectorData::isAvailableWritableAsDecoration (auxid_t id) const
{
  // First check to see if this variable is present in the cache.
  if (m_decorCache.cachePtr (id)) return true;
  return isAvailableWritableAsDecorationOol (id);
}
 
 
/**
 * @brief Return reference to an aux data item.
 * @param auxid The desired aux data item.
 * @param ndx Index of the element to return.
 *
 * This will return a reference to element @c ndx of aux data item @c auxid.
 * If the aux data item does not exist, it will be created.
 * Errors are signaled by raising an exception.
 *
 * Warning: no type checking is done.  You should usually access
 * the data via @c Accessor.
 */
template <class T>
inline
typename AuxDataTraits<T>::reference_type
AuxVectorData::getData (SG::auxid_t auxid, size_t ndx)
{
  return AuxDataTraits<T>::index (this->getDataArray (auxid), ndx);
}
 
 
/**
 * @brief Return const reference to an aux data item.
 * @param auxid The desired aux data item.
 * @param ndx Index of the element to return.
 *
 * This will return a reference to element @c ndx of aux data item @c auxid.
 * If the aux data item does not exist, it will be created.
 * Errors are signaled by raising an exception.
 *
 * Warning: no type checking is done.  You should usually access
 * the data via @c Accessor.
 */
template <class T>
inline
typename AuxDataTraits<T>::const_reference_type
AuxVectorData::getData (SG::auxid_t auxid, size_t ndx) const
{
  return AuxDataTraits<T>::index (this->getDataArray (auxid), ndx);
}
 
 
/**
 * @brief Return reference to an aux decoration item.
 * @param auxid The desired aux decoration item.
 * @param ndx Index of the element to return.
 *
 * This will return a reference to element @c ndx of aux decoration
 * item @c auxid.
 * If the aux data item does not exist, it will be created.
 * Errors are signaled by raising an exception.
 *
 * Warning: no type checking is done.  You should usually access
 * the data via @c Decorator.
 *
 * The difference between @c getDecoration and @c getData is that
 * @c getDecoration takes a const container as input, but returns
 * a non-const reference.  This will only succeed if either the
 * container is not locked or the item was first accessed
 * as a decoration.
 */
template <class T>
inline
typename AuxDataTraits<T>::reference_type
AuxVectorData::getDecoration (SG::auxid_t auxid, size_t ndx) const
{
  return AuxDataTraits<T>::index (this->getDecorationArray (auxid), ndx);
}
 
 
 
/**
 * @brief Return a pointer to the start of an aux data vector.
 * @param auxid The desired aux data item.
 *
 * This will return a pointer to the start of the data for aux
 * data item @c auxid.  If the item doesn't exist, it will be created.
 * Errors are signaled by raising an exception.
 */
inline
void*
AuxVectorData::getDataArray (SG::auxid_t auxid)
{
  return m_cache.getDataArray (auxid, *this);
}
 
 
/**
 * @brief Return a const pointer to the start of an aux data vector.
 * @param auxid The desired aux data item.
 *
 * This will return a pointer to the start of the data for aux
 * data item @c auxid.
 * Errors are signaled by raising an exception.
 */
inline
const void*
AuxVectorData::getDataArray (SG::auxid_t auxid) const
{
  return m_constCache.getDataArray (auxid, *this);
}
 
 
/**
 * @brief Return a const pointer to the start of an aux data vector.
 * @param auxid The desired aux data item.
 *
 * This will return a pointer to the start of the data for aux
 * data item @c auxid.  If the item does not exist,
 * this will return nullptr rather than raising an exception.
 */
inline
const void*
AuxVectorData::getDataArrayAllowMissing (SG::auxid_t auxid) const
{
  return m_constCache.getDataArrayAllowMissing (auxid, *this);
}
 
 
/**
 * @brief Return a pointer to the start of an aux data vector for a decoration.
 * @param auxid The desired aux data item.
 *
 * This will return a pointer to the start of the data for aux
 * data item @c auxid.  If the item doesn't exist, it will be created.
 * Errors are signaled by raising an exception.
 *
 * The difference between @c getDecorationArray and @c getDataArray is that
 * @c getDecorationArray takes a const container as input, but returns
 * a non-const pointer.  This will only succeed if either the
 * container is not locked or the item was first accessed
 * as a decoration.
 */
inline
void* AuxVectorData::getDecorationArray (SG::auxid_t auxid) const
{
  return m_decorCache.getDecorationArray (auxid, *this);
}
 
 
/**
 * @brief Return a reference to a description of this vector's start+size.
 * @param auxid The desired aux data item.
 *
 * This low-overhead method of getting the start+size of an auxiliary
 * variable.  The returned object will be updated if the variable's
 * vector changes.  Raises an exception if the variable does not exist.
 *
 * This is in principle a const-correctness violation,
 * since @c AuxDataSpanBase has a non-const pointer to the start
 * of the vector.  But doing it properly is kind of painful, and as
 * this interface is only meant to be used internally, it's likely
 * not a real problem.
 */
inline
const AuxDataSpanBase*
AuxVectorData::getDataSpan (SG::auxid_t auxid) const
{
  return m_spanCache.getDataSpan (auxid, *this);
}
 
 
/**
 * @brief Swap this instance with another.
 * @param other The other instance with which to swap.
 */
inline
void AuxVectorData::swap (AuxVectorData& other)
{
  m_cache.swap (other.m_cache);
  m_constCache.swap (other.m_constCache);
  m_decorCache.swap (other.m_decorCache);
  m_spanCache.swap (other.m_spanCache);
  std::swap (m_store, other.m_store);
  std::swap (m_constStore, other.m_constStore);
  std::swap (m_constStoreLink, other.m_constStoreLink);
}
 
 
/**
 * @brief Clear the cached aux data pointers.
 *
 * You should call this anytime something changes in the aux store
 * that could invalidate the vector pointers.
 */
inline
void AuxVectorData::clearCache()
{
  guard_t guard (m_mutex);
  m_cache.clear();
  m_constCache.clear();
  m_decorCache.clear();
  m_spanCache.clear();
}
 
 
/**
 * @brief Clear the cached aux data pointers for a single variable.
 * @param auxid ID of the variable to clear.
 *
 * Not really safe to use if another thread may be accessing
 * the same decoration.
 */
inline
void AuxVectorData::clearCache (SG::auxid_t auxid)
{
  guard_t guard (m_mutex);
  m_cache.clear (auxid);
  m_constCache.clear (auxid);
  m_decorCache.clear (auxid);
  // Don't clear the span cache here --- the referenced spans get updated
  // automatically as needed.
}
 
 
/**
 * @brief Clear the cached decoration pointer for a single variable.
 * @param auxid ID of the variable to clear.
 *
 * Not really safe to use if another thread may be accessing
 * the same decoration.
 */
inline
void AuxVectorData::clearDecorCache (SG::auxid_t auxid)
{
  guard_t guard (m_mutex);
  m_decorCache.clear (auxid);
}
 
 
/**
 * @brief Test to see if @c auxid is valid in the cache.
 * @returns If @c auxid is valid, return the pointer to the vector, else 0.
 */
inline
void* AuxVectorData::Cache::cachePtr (SG::auxid_t auxid)
{
  // This function is important for performance.
  // Be careful when changing it.
 
  // auxid must not be larger than the length of the cache vector.
  if (auxid >= m_cache_len) return 0;
#if !(defined(__x86_64__) || defined(__i386))
  // Memory fence not strictly required on x86, and spoils optimizations.
  // See header comments.
  AthContainers_detail::fence_acq_rel();
#endif
  // Return the cache entry.
  return m_cache[m_cache_len&1][auxid];
}
 
 
/**
 * @brief Return a pointer to the start of an aux data vector.
 * @param auxid The desired aux data item.
 * @param parent The containing @c AuxVectorData object.
 *
 * This will return a pointer to the start of the data for aux
 * data item @c auxid.  If the item doesn't exist, it will be created.
 * Errors are signaled by raising an exception.
 */
inline
void*
AuxVectorData::Cache::getDataArray (SG::auxid_t auxid,
                                    AuxVectorData& parent)
{
  // This function is important for performance.
  // Be careful when changing it.
 
  void* ptr = cachePtr (auxid);
  if (ATHCONTAINERS_UNLIKELY (ptr == 0)) {
    // We don't have the variable cached.
    // Call the out-of-line routine to get it cached.
    ptr = parent.getDataOol (auxid, false);
 
    // These inform the compiler of what the previous call did.
    // They tell the optimizer that it can now assume that this cache
    // entry is valid.
    ATHCONTAINERS_ASSUME (ptr != 0);
    ATHCONTAINERS_ASSUME (cachePtr (auxid) != 0);
    ATHCONTAINERS_ASSUME (cachePtr (auxid) == ptr);
  }
  return ptr;
}
 
 
/**
 * @brief Return a const pointer to the start of an aux data vector.
 * @param auxid The desired aux data item.
 * @param parent The containing @c AuxVectorData object.
 *
 * This will return a pointer to the start of the data for aux
 * data item @c auxid.
 * Errors are signaled by raising an exception.
 */
inline
const void*
AuxVectorData::Cache::getDataArray (SG::auxid_t auxid,
                                    const AuxVectorData& parent)
{
  // This function is important for performance.
  // Be careful when changing it.
 
  const void* ptr = cachePtr (auxid);
  if (ATHCONTAINERS_UNLIKELY (ptr == 0)) {
    // We don't have the variable cached.
    // Call the out-of-line routine to get it cached.
    ptr = parent.getDataOol (auxid, false);
 
    // These inform the compiler of what the previous call did.
    // They tell the optimizer that it can now assume that this cache
    // entry is valid.
    ATHCONTAINERS_ASSUME (ptr != 0);
    ATHCONTAINERS_ASSUME (cachePtr (auxid) != 0);
    ATHCONTAINERS_ASSUME (cachePtr (auxid) == ptr);
  }
  return ptr;
}
 
 
/**
 * @brief Return a const pointer to the start of an aux data vector.
 * @param auxid The desired aux data item.
 * @param parent The containing @c AuxVectorData object.
 *
 * This will return a pointer to the start of the data for aux
 * data item @c auxid.  If the item does not exist,
 * this will return nullptr rather than raising an exception.
 */
inline
const void*
AuxVectorData::Cache::getDataArrayAllowMissing (SG::auxid_t auxid,
                                                const AuxVectorData& parent)
{
  const void* ptr = cachePtr (auxid);
  if (ATHCONTAINERS_UNLIKELY (ptr == 0)) {
    // We don't have the variable cached.
    // Call the out-of-line routine to get it cached.
    ptr = parent.getDataOol (auxid, true);
  }
  return ptr;
}
 
 
/**
 * @brief Return a pointer to the start of an aux decoration vector.
 * @param auxid The desired aux decoration item.
 * @param parent The containing @c AuxVectorData object.
 *
 * This will return a pointer to the start of the data for aux
 * decoration item @c auxid.  If the item doesn't exist, it will be created.
 * Errors are signaled by raising an exception.
 *
 * The difference between @c getDecorationArray and @c getDataArray is that
 * @c getDecorationArray takes a const container as input, but returns
 * a non-const pointer.  This will only succeed if either the
 * container is not locked or the item was first accessed
 * as a decoration.
 */
inline
void* AuxVectorData::Cache::getDecorationArray (SG::auxid_t auxid,
                                                const AuxVectorData& parent)
{
  // This function is important for performance.
  // Be careful when changing it.
 
  void* ptr = cachePtr (auxid);
  if (ATHCONTAINERS_UNLIKELY (ptr == 0)) {
    // We don't have the variable cached.
    // Call the out-of-line routine to get it cached.
    ptr = parent.getDecorationOol (auxid);
 
    // These inform the compiler of what the previous call did.
    // They tell the optimizer that it can now assume that this cache
    // entry is valid.
    ATHCONTAINERS_ASSUME (ptr != 0);
    ATHCONTAINERS_ASSUME (cachePtr (auxid) != 0);
    ATHCONTAINERS_ASSUME (cachePtr (auxid) == ptr);
  }
  return ptr;
}
 
 
/**
 * @brief Return a reference to a description of this vector's start+size.
 * @param auxid The desired aux data item.
 */
inline
const AuxDataSpanBase*
AuxVectorData::Cache::getDataSpan (SG::auxid_t auxid,
                                   const AuxVectorData& parent)
{
  // This function is important for performance.
  // Be careful when changing it.
 
  const void* ptr = cachePtr (auxid);
  if (ATHCONTAINERS_UNLIKELY (ptr == 0)) {
    // We don't have the variable cached.
    // Call the out-of-line routine to get it cached.
    ptr = static_cast<const void*>(parent.getDataSpanOol (auxid, false));
 
    // These inform the compiler of what the previous call did.
    // They tell the optimizer that it can now assume that this cache
    // entry is valid.
    //ATHCONTAINERS_ASSUME (ptr != 0);
  }
  return reinterpret_cast<const AuxDataSpanBase*> (ptr);
}
 
 
/**
 * @brief Set an option for an auxiliary data variable.
 * @param id The variable for which we want to set the option.
 * @param optname The name of the option to set.
 * @param arg The option value to set.
 *
 * The interpretation of @c option depends on the associated auxiliary store.
 * See PackedParameters.h for option settings for writing packed data.
 * Returns @c true on success, @c false otherwise.
 */
template <class T>
bool AuxVectorData::setOption (auxid_t id,
                               const std::string& optname,
                               T arg)
{
  return this->setOption (id, AuxDataOption (optname, arg));
}
 
 
/**
 * @brief Set an option for an auxiliary data variable.
 * @param name The name of the variable.
 * @param optname The name of the option to set.
 * @param arg The option value to set.
 *
 * The interpretation of @c option depends on the associated auxiliary store.
 * See PackedParameters.h for option settings for writing packed data.
 * Returns @c true on success, @c false otherwise.
 */
inline
bool AuxVectorData::setOption (const std::string& name,
                               const std::string& optname,
                               int arg)
{
  return this->setOption (name, AuxDataOption (optname, arg));
}
inline
bool AuxVectorData::setOption (const std::string& name,
                               const std::string& optname,
                               float arg)
{
  return this->setOption (name, AuxDataOption (optname, arg));
}
inline
bool AuxVectorData::setOption (const std::string& name,
                               const std::string& optname,
                               double arg)
{
  return this->setOption (name, AuxDataOption (optname, arg));
}
 
 
/**
 * @brief Set an option for an auxiliary data variable.
 * @param name The name of the variable.
 * @param clsname The name of the associated class.  May be blank.
 * @param optname The name of the option to set.
 * @param arg The option value to set.
 *
 * The interpretation of @c option depends on the associated auxiliary store.
 * See PackedParameters.h for option settings for writing packed data.
 * Returns @c true on success, @c false otherwise.
 */
template <class T>
bool AuxVectorData::setOption (const std::string& name,
                               const std::string& clsname,
                               const std::string& optname,
                               T arg)
{
  return this->setOption (name, clsname, AuxDataOption (optname, arg));
}
 
 
/**
 * @brief Explicitly set a cache pointer.
 * @param auxid Variable ID to set.
 * @param ptr Pointer to which the cache entry should be set.
 *
 * For internal use; do not use from user code.
 * This does _not_ acquire the lock --- it's mostly meant to be used
 * from a constructor.
 */
inline
void AuxVectorData::setCache (SG::auxid_t auxid, void* ptr)
{
  m_cache.store (auxid, ptr);
}
 
 
/**
 * @brief Explicitly set a cache pointer.
 * @param auxid Variable ID to set.
 * @param ptr Pointer to which the cache entry should be set.
 *
 * For internal use; do not use from user code.
 * This does _not_ acquire the lock --- it's mostly meant to be used
 * from a constructor.
 */
inline
void AuxVectorData::setCache (SG::auxid_t auxid, const void* ptr)
{
  // Ok; usage of ptr is still const.
  void* ptr_nc ATLAS_THREAD_SAFE = const_cast<void*>(ptr);
  m_constCache.store (auxid, ptr_nc);
}
 
 
} // namespace SG