RCUObject.icc

Go to the documentation of this file.

/*
  Copyright (C) 2002-2022 CERN for the benefit of the ATLAS collaboration
*/
/**
 * @file AthenaKernel/RCUObject.icc
 * @author scott snyder <snyder@bnl.gov>
 * @date Aug, 2016
 * @brief read-copy-update (RCU) style synchronization for Athena.
 */
 
 
namespace Athena {
 
 
/**
 * @brief Declare the current event slot of this object to be quiescent.
 *
 * This will take out a lock and possibly trigger object cleanup.
 */
inline
void IRCUObject::quiescent()
{
  quiescent (Gaudi::Hive::currentContext());
}
 
 
/**
 * @brief Declare the event slot @c ctx of this object to be quiescent.
 * @param ctx The event context.
 *
 * This will take out a lock and possibly trigger object cleanup.
 */
inline
void IRCUObject::quiescent (const EventContext& ctx)
{
  if (!m_dirty) return;
  lock_t g (m_mutex);
  if (!endGrace(g, ctx, m_grace)) {
    clearAll(g);
    m_nold = 0;
    m_dirty = false;
  }
  else if (m_nold > 0 && !endGrace(g, ctx, m_oldGrace)) {
    if (clearOld(g, m_nold)) {
      m_dirty = false;
    }
    m_nold = 0;
  }
}
 
 
/**
 * @brief Declare that the grace period for a slot is ending.
 * @param lock Lock object (external locking).
 * @param ctx Event context for the slot.
 * @returns true if any slot is still in a grace period.
 *          false if no slots are in a grace period.
 *
 * The caller must be holding the mutex for this object.
 */
inline
bool IRCUObject::endGrace (lock_t& lock, const EventContext& ctx)
{
  return endGrace (lock, ctx, m_grace);
}
 
 
/**
 * @brief Declare that all slots are in a grace period.
 * @param Lock object (external locking).
 *
 * The caller must be holding the mutex for this object.
 */
inline
void IRCUObject::setGrace (lock_t& /*lock*/)
{
  m_grace.set();
  if (!m_dirty) m_dirty = true;
}
 
 
/**
 * @brief Return the mutex for this object.
 */
inline
typename IRCUObject::mutex_t& IRCUObject::mutex()
{
  return m_mutex;
}
 
 
/**
 * @brief Make existing pending objects old, if possible.
 * @param lock Lock object (external locking).
 * @param garbageSize Present number of objects pending deletion.
 *
 * A new object is about to be added to the list of objects pending deletion.
 * If there are any existing pending objects and there are no existing
 * old objects, make the current pending objects old.
 */
inline
void IRCUObject::makeOld (lock_t& /*lock*/, size_t garbageSize)
{
  if (garbageSize && m_nold == 0) {
    m_oldGrace = m_grace;
    m_nold = garbageSize;
  }
}
 
 
/**
 * @brief Declare that the grace period for a slot is ending.
 * @param Lock object (external locking).
 * @param ctx Event context for the slot.
 * @param grace Bitmask tracking grace periods.
 * @returns true if any slot is still in a grace period.
 *          false if no slots are in a grace period.
 *
 * The caller must be holding the mutex for this object.
 */
inline
bool IRCUObject::endGrace (lock_t& /*lock*/,
                           const EventContext& ctx,
                           boost::dynamic_bitset<>& grace) const
{
  EventContext::ContextID_t slot = ctx.slot();
  if (slot == EventContext::INVALID_CONTEXT_ID) return false;
  if (slot >= grace.size()) std::abort();
  grace[slot] = false;
  return grace.any();
}
 
 
//*************************************************************************
 
 
/**
 * @brief Constructor, with RCUSvc.
 * @param svc Service with which to register.
 * @param args... Additional arguments to pass to the @c T constructor.
 *
 * The service will call @c quiescent at the end of each event.
 */
template <class T>
template <typename... Args>
inline
RCUObject<T>::RCUObject (IRCUSvc& svc, Args&&... args)
  : IRCUObject (svc),
    m_objref (std::make_unique<T>(std::forward<Args>(args)...)),
    m_obj (m_objref.get())
{
}
 
 
/**
 * @brief Constructor, with number of slots.
 * @param nslots Number of event slots.
 * @param args... Additional arguments to pass to the @c T constructor.
 */
template <class T>
template <typename... Args>
inline
RCUObject<T>::RCUObject (size_t nslots, Args&&... args)
  : IRCUObject (nslots),
    m_objref (std::make_unique<T>(std::forward<Args>(args)...)),
    m_obj (m_objref.get())
{
}
 
 
/**
 * @brief Constructor, with RCUSvc.
 * @param svc Service with which to register.
 *
 * The service will call @c quiescent at the end of each event.
 * No current object will be created.
 */
template <class T>
inline
RCUObject<T>::RCUObject (IRCUSvc& svc, NoObjectEnum)
  : IRCUObject (svc),
    m_objref(),
    m_obj (nullptr)
{
}
 
 
/**
 * @brief Move constructor.
 *
 * Allow passing these objects via move.
 */
template <class T>
RCUObject<T>::RCUObject (RCUObject&& other)
  : IRCUObject (std::move (other)),
    m_objref (std::move (other.m_objref)),
    m_obj (static_cast<const T*> (other.m_obj)),
    m_garbage (std::move (other.m_garbage))
{
  other.m_obj = nullptr;
}
 
 
/**
 * @brief Return a reader for this @c RCUObject.
 */
template <class T>
inline
typename RCUObject<T>::Read_t RCUObject<T>::reader() const
{
  return Read_t (*this);
}
 
 
/**
 * @brief Return a reader for this @c RCUObject.
 *        When destroyed, this reader will declare
 *        the @c RCUObject as quiescent
 *
 * This version will read the global event context.
 */
template <class T>
inline
typename RCUObject<T>::ReadQuiesce_t RCUObject<T>::readerQuiesce()
{
  return ReadQuiesce_t (*this);
}
 
 
/**
 * @brief Return a reader for this @c RCUObject.
 *        When destroyed, this reader will declare
 *        the @c RCUObject as quiescent
 * @param ctx The event context.
 */
template <class T>
inline
typename RCUObject<T>::ReadQuiesce_t
RCUObject<T>::readerQuiesce (const EventContext& ctx)
{
  return ReadQuiesce_t (*this, ctx);
}
 
 
/**
 * @brief Return an updater for this @c RCUObject.
 *
 * This version will read the global event context.
 */
template <class T>
inline
typename RCUObject<T>::Update_t RCUObject<T>::updater()
{
  return Update_t (*this);
}
 
 
/**
 * @brief Return an updater for this @c RCUObject.
 *
 * This version will read the global event context.
 */
template <class T>
inline
typename RCUObject<T>::Update_t
RCUObject<T>::updater (const EventContext& ctx)
{
  return Update_t (*this, ctx);
}
 
 
/**
 * @brief Queue an object for later deletion.
 * @param p The object to delete.
 *
 * The object @c p will be queued for deletion once a grace period
 * has passed for all slots.  In contrast to using @c updater,
 * this does not change the current object.  It also does not mark
 * the current slot as having completed the grace period (so this can
 * be called by a thread running outside of a slot context).
 */
template <class T>
void RCUObject<T>::discard (std::unique_ptr<const T> p)
{
  lock_t g (mutex());
  discard (g, std::move (p));
}
 
 
/**
 * @brief Queue an object for later deletion.
 * @param lock Lock object (external locking).
 * @param p The object to delete.
 */
template <class T>
void RCUObject<T>::discard (lock_t& lock, std::unique_ptr<const T> p)
{
  makeOld (lock, m_garbage.size());
  m_garbage.push_front (std::move (p));
  setGrace (lock);
}
 
 
/**
 * @brief Delete all objects.
 * @param Lock object (external locking).
 *
 * The caller must be holding the mutex for this object.
 */
template <class T>
inline
void RCUObject<T>::clearAll (lock_t& /*lock*/)
{
  m_garbage.clear();
}
 
 
/**
 * @brief Delete old objects.
 * @param Lock object (external locking).
 * @param nold Number of old objects to delete.
 *
 * The caller must be holding the mutex for this object.
 * Returns true if there are no more objects pending deletion.
 */
template <class T>
inline
bool RCUObject<T>::clearOld (lock_t& /*lock*/, size_t nold)
{
  while (nold > 0) {
    m_garbage.pop_back();
    --nold;
  }
  return m_garbage.empty();
}
 
 
//*************************************************************************
 
 
/**
 * @brief Constructor.
 * @param rcuobj The @c RCUObject we're reading.
 */
template <class T>
inline
RCURead<T>::RCURead (const RCUObject<T>& rcuobj)
  : m_obj (rcuobj.m_obj)
{
}
 
 
/**
 * @brief Access data.
 */
template <class T>
inline
const T& RCURead<T>::operator*() const
{
  return *m_obj;
}
 
 
/**
 * @brief Access data.
 */
template <class T>
inline
const T* RCURead<T>::operator->() const
{
  return m_obj;
}
 
 
//*************************************************************************
 
 
/**
 * @brief Constructor.
 * @param rcuobj The @c RCUObject we're reading.
 *
 * This version will read the global event context.
 */
template <class T>
inline
RCUReadQuiesce<T>::RCUReadQuiesce (RCUObject<T>& rcuobj)
  : RCURead<T> (rcuobj),
    m_rcuobj (rcuobj),
    m_ctx (Gaudi::Hive::currentContext())
{
}
 
 
/**
 * @brief Constructor.
 * @param rcuobj The @c RCUObject we're reading.
 * @param ctx The event context.
 */
template <class T>
inline
RCUReadQuiesce<T>::RCUReadQuiesce (RCUObject<T>& rcuobj,
                                   const EventContext& ctx)
  : RCURead<T> (rcuobj),
    m_rcuobj (rcuobj),
    m_ctx (ctx)
{
}
 
 
/**
 * @brief Destructor.
 *
 * Mark this event slot quiescent.
 */
template <class T>
inline
RCUReadQuiesce<T>::~RCUReadQuiesce()
{
  m_rcuobj.quiescent (m_ctx);
}
 
 
//*************************************************************************
 
 
/**
 * @brief Constructor.
 * @param rcuobj The @c RCUObject we're reading.
 *
 * This version will read the global event context.
 */
template <class T>
inline
RCUUpdate<T>::RCUUpdate (RCUObject<T>& rcuobj)
  : m_rcuobj (rcuobj),
    m_ctx (Gaudi::Hive::currentContext()),
    m_g (rcuobj.mutex())
{
}
 
 
/**
 * @brief Constructor.
 * @param rcuobj The @c RCUObject we're reading.
 * @param ctx The event context.
 */
template <class T>
inline
RCUUpdate<T>::RCUUpdate (RCUObject<T>& rcuobj, const EventContext& ctx)
  : m_rcuobj (rcuobj),
    m_ctx (ctx),
    m_g (rcuobj.mutex())
{
}
 
 
/**
 * @brief Access data.
 */
template <class T>
inline
const T& RCUUpdate<T>::operator*() const
{
  return *m_rcuobj.m_obj;
}
 
 
/**
 * @brief Access data.
 */
template <class T>
inline
const T* RCUUpdate<T>::operator->() const
{
  return m_rcuobj.m_obj;
}
 
 
/**
 * @brief Publish a new version of the data object.
 * @param ptr The new data object.
 */
template <class T>
void RCUUpdate<T>::update (std::unique_ptr<T> ptr)
{
  // Queue the current object for deletion, if it exists.
  if (m_rcuobj.m_objref) {
    m_rcuobj.discard (m_g, std::move (m_rcuobj.m_objref));
  }
 
  // Install the new object.
  m_rcuobj.m_objref = std::move (ptr);
  m_rcuobj.m_obj = m_rcuobj.m_objref.get();
 
  // Go ahead and end the grace period for the current slot.
  m_rcuobj.endGrace(m_g, m_ctx);
}
 
 
} // namespace Athena