CaloCellPrefetchIterator.h

Go to the documentation of this file.

// This file's extension implies that it's C, but it's really -*- C++ -*-.
 
/*
  Copyright (C) 2002-2022 CERN for the benefit of the ATLAS collaboration
*/
 
 
#ifndef CALOEVENT_CALOCELLPREFETCHITERATOR_H
#define CALOEVENT_CALOCELLPREFETCHITERATOR_H
 
 
#include "CaloEvent/CaloCell.h"
#include "Navigation/NavigationToken.h"
#include <iterator>
 
 
// Forward declaration.
template <class T>
class CaloCellPrefetchIterator;
 
 
namespace CaloEvent_detail {
 

template <class T, class TAG>
struct paramholder
{
  typedef int param_t;

  param_t getParameter() const;
 
 
private:
  friend class CaloCellPrefetchIterator<T>;

  void next ();

  void fetch (const T& it);
};
 

template <class T>
struct paramholder<T, NavigationTokenIteratorTag>
{
  typedef typename T::tokenParameter param_t;

  param_t getParameter() const;
 
 
private:
  friend class CaloCellPrefetchIterator<T>;

  void next ();

  void fetch (const T& it);

  param_t m_param;

  param_t m_next_param;
};
 
 
} // namespace CaloEvent_detail
 
 
 
/*
 * @brief To iterate over @a CaloCell's, prefetching the detector description.
 *
 * A typical use of @a CaloCell's is to iterate over a container of them;
 * for each cell, we then call methods on the detector descriptor element
 * for that cell.  It will often be the case, though, that the DDE data
 * are not in cache when first accessed.  This will show up in profiles
 * as the first DDE accessor method taking much longer than subsequent ones.
 *
 * A way to mitigate this is to use the prefetch feature of the x86 CPUs.
 * At the start of the loop, we look ahead at the next cell to be processed
 * and issue a prefetch for its DDE.  The prefetch itself won't stall, and
 * when we come around to the next iteration of the loop, it is likely
 * that the DDE data are now in cache.
 *
 * Here is an example of how to use this:
 *
 *@code
   CONTAINER container = ...;
   CaloCellPrefetchIterator<CONTAINER::const_iterator> it
     (container.begin(), container.end());
   while (it.next()) {
     const CaloCell* cellp = *it;
   }
 @endcode
 *
 * If the container is a @a NavigableToken, you can also get the parameter
 * with <code>it.getParameter()</code>.
 *
 * As a convenience, you can also say
 *
 *@code
   CaloCellPrefetchIterator<CONTAINER::const_iterator> it  (container);
 @endcode
 *
 * Note that there must be no null pointers in the collection.
 *
 * Also note that the prefetch instructions won't actually be generated
 * unless -msse is used during compilation.  (This is for x86; other
 * architectures may require other switches.)
 *
 * (Originally, the intention was to make this be a STL-style iterator
 * so that it could be a drop-in replacement.  It proved impractical
 * to do it that way and have it also be efficient and robust.)
 *
 * Because iterators may be heavy-weight (such as for
 * @c NavigableTokenIterator), we keep only the current and end
 * iterators here.  We separately cache the cell pointers (and weights)
 * for the current and next elements.  We're careful to only
 * do the iterator comparison once per loop.
 */
template <class T>
class CaloCellPrefetchIterator
  : public CaloEvent_detail::paramholder<T, typename T::iterator_category>
{
public:
  typedef T base_iterator;
 
  using iterator_category = std::forward_iterator_tag;
  using value_type = const CaloCell*;
  using difference_type = std::ptrdiff_t;
  using pointer = value_type*;
  using reference = value_type&;

  typedef CaloEvent_detail::paramholder<T, typename T::iterator_category>
    paramholder;
 

  CaloCellPrefetchIterator (const base_iterator& begin,
                            const base_iterator& end);
 

  template <class CONTAINER>
  CaloCellPrefetchIterator (const CONTAINER& cont);
 

  bool next();
 

  const CaloCell* operator*() const;

  using paramholder::getParameter;
 
 
private:
  void init();

  const CaloCell* m_cellp;

  const CaloCell* m_next_cellp;

  T m_it;

  T m_end;
};
 
 
#include "CaloEvent/CaloCellPrefetchIterator.icc"
 
 
#endif // not CALOEVENT_CALOCELLPREFETCHITERATOR_H