DataHandleHolderBase.h

Go to the documentation of this file.

#ifndef GAUDIKERNEL_DATAHANDLEHOLDERBASE
#define GAUDIKERNEL_DATAHANDLEHOLDERBASE 1

#include <algorithm>
#include <type_traits>
#include <unordered_set>
#include <vector>

#include <boost/optional.hpp>

#include "GaudiKernel/DataHandle.h"
#include "GaudiKernel/DataObjID.h"
#include "GaudiKernel/GaudiException.h"
#include "GaudiKernel/IDataHandleHolder.h"
#include "GaudiKernel/IStateful.h"
#include "GaudiKernel/Property.h"
#include "GaudiKernel/StateMachine.h"

template <typename BASE>
class GAUDI_API DataHandleHolderBase : public extends<BASE, IDataHandleHolder>
{
  using Super      = extends<BASE, IDataHandleHolder>;
  using AccessMode = Gaudi::v2::DataHandle::AccessMode;

public:
  template <typename... Args>
  DataHandleHolderBase( Args&&... args ) : Super( std::forward<Args>( args )... )
  {
  }

  void registerDataHandle( Gaudi::v2::DataHandle& handle ) final override
  {
    if ( m_explicitDepsCollected && isNewDataDependency( handle ) ) {
      throw GaudiException( "Cannot register a new data handle after data dependency collection", this->name(),
                            StatusCode::FAILURE );
    }
    auto index = accessToIndex( handle.access() );
    m_dataHandles[index].push_back( &handle );
  }

  void addDataDependency( const DataObjID& key, AccessMode access ) final override
  {
    auto index = accessToIndex( access );
    m_dataDepKeys[index].insert( key );
  }

  const DataObjIDColl& dataDependencies( AccessMode access ) const final override
  {
    auto index = accessToIndex( access );
    return allDataDependencies()[index];
  }

  void declare( Gaudi::v1::DataHandle& handle ) override
  {
    if ( m_explicitDepsCollected && isNewDataDependency( handle ) ) {
      throw GaudiException( "Cannot register a new data handle after data dependency collection", this->name(),
                            StatusCode::FAILURE );
    }

    if ( !handle.owner() ) {
      handle.setOwner( this );
    } else if ( handle.owner() != this ) {
      throw GaudiException( "Attempt to declare foreign handle with algorithm!", this->name(), StatusCode::FAILURE );
    }

    m_legacyHandles.insert( &handle );
  }

  void renounce( Gaudi::v1::DataHandle& handle ) override
  {
    // In general, deleting a DataHandle after the data dependencies have been
    // collected is bogus, because this change will not propagate to the data
    // dependency list, and to our clients that have queried and potentially
    // made copies of this list, such as the Scheduler.
    //
    // Nevertheless, this operation is safe and should be allowed during
    // and after Algorithm finalization.
    //
    if ( m_explicitDepsCollected &&
         dynamic_cast<IStateful*>( this )->targetFSMState() >= Gaudi::StateMachine::INITIALIZED ) {
      throw GaudiException( "Cannot discard legacy handle after data dependency collection", this->name(),
                            StatusCode::FAILURE );
    }

    if ( handle.owner() != this ) {
      throw GaudiException( "Attempt to renounce foreign handle with algorithm!", this->name(), StatusCode::FAILURE );
    }

    m_legacyHandles.erase( &handle );
  }

  // Access the internal array of data dependencies. This is only meant for
  // internal use, but must be public as we access it via IDataHandleHolder.
  const DataObjIDColl* allDataDependencies() const final override
  {
    if ( !m_explicitDepsCollected ) {
      throw GaudiException( "Cannot read data dependencies before they are collected", this->name(),
                            StatusCode::FAILURE );
    }
    return m_dataDepKeys;
  }

protected:
  using DataObjIDMapping = std::function<boost::optional<DataObjID>( const DataObjID& )>;

  void updateDataDependencies( const DataObjIDMapping& keyMap )
  {
    updateDependencies( m_dataHandles, keyMap );
    updateDependencies( m_legacyHandles, keyMap );
    updateDependencies( m_dataDepKeys, keyMap );
    updateDependencies( m_extraDeps, keyMap );
  }

  void collectExplicitDataDependencies()
  {
    // Considering this function's interface contract, calling it multiple
    // times is very likely to be the result of a usage error.
    if ( m_explicitDepsCollected ) {
      throw GaudiException( "Explicit dependencies may only be collected once", this->name(), StatusCode::FAILURE );
    }

    // Collect the centralized lists of inputs and outputs
    collectDependencies( m_dataHandles );
    collectDependencies( m_extraDeps );
    collectDependencies( m_legacyHandles );

    // Take note that the explicit dependencies have been collected
    m_explicitDepsCollected = true;
  }

  enum class CircularDepAction {
    Abort,

    Ignore
  };

  using CircularDepHandler = std::function<CircularDepAction( const DataObjID& )>;

  StatusCode handleCircularDataDependencies( CircularDepHandler&& circularDepHandler )
  {
    // Make sure that explicit dependencies have been collected beforehand
    if ( !m_explicitDepsCollected ) {
      throw GaudiException( "Explicit dependencies must be collected first", this->name(), StatusCode::FAILURE );
    }

    // Go through the output dependencies, looking for circular input
    // dependencies
    //
    // We must use this inefficient O(N²) iteration pattern because circular
    // dependency handling may mutate the input dependency list,
    // invalidating any iterator to that list.
    //
    const DataObjIDColl& outputKeys = m_dataDepKeys[accessToIndex( AccessMode::Write )];
    DataObjIDColl&       inputKeys  = m_dataDepKeys[accessToIndex( AccessMode::Read )];
    for ( const auto& outputKey : outputKeys ) {
      auto inputPos = inputKeys.find( outputKey );
      if ( inputPos != inputKeys.end() ) {
        // Call the user circular dependency handler on each dependency
        switch ( circularDepHandler( *inputPos ) ) {
        // Abort iteration if asked to do so
        case CircularDepAction::Abort:
          return StatusCode::FAILURE;

        // Break the circular dependency otherwise
        case CircularDepAction::Ignore:
          inputKeys.erase( inputPos );
        }
      }
    }

    // If control reached this point, we are fine
    return StatusCode::SUCCESS;
  }

  void collectImplicitDataDependencies( const IDataHandleHolder* child )
  {
    if ( !child ) return; // Framework randomly sends nulls to this function...
    collectDependencies( child->allDataDependencies() );
  }

  const DataObjIDColl& ignoredDataDependencies( AccessMode access ) const
  {
    if ( !m_explicitDepsCollected ) {
      throw GaudiException( "Cannot read ignored data dependencies before they are collected", this->name(),
                            StatusCode::FAILURE );
    }
    return m_ignoredDataDeps[accessToIndex( access )];
  }

  void initializeDataHandleHolder()
  {
    for ( auto handle : m_legacyHandles ) handle->init();

    for ( auto handleArray : m_dataHandles ) {
      for ( auto handle : handleArray ) {
        handle->initialize( *this );
      }
    }
  }

private:
  // We need to know the number of DataHandle access modes
  static constexpr size_t NUM_ACCESS_MODES = static_cast<size_t>( AccessMode::NUM_ACCESS_MODES );

  // Data handles associated with input and output data
  using DataHandleList = std::vector<Gaudi::v2::DataHandle*>;
  DataHandleList m_dataHandles[NUM_ACCESS_MODES];

  // Legacy DataHandles
  std::unordered_set<Gaudi::v1::DataHandle*> m_legacyHandles;

  // Properties allowing extra input and output dependencies to be
  // declared at configuration time.
  static_assert( NUM_ACCESS_MODES == 2,
                 "This part of the code assumes that there are only two DataHandle access modes" );
  static_assert( static_cast<size_t>( AccessMode::Read ) == 0,
                 "This part of the code assumes that \"Read\" comes first in the AccessMode enum" );
  Gaudi::Property<DataObjIDColl> m_extraDeps[NUM_ACCESS_MODES]{{this, "ExtraInputs", DataObjIDColl{}},
                                                               {this, "ExtraOutputs", DataObjIDColl{}}};

  // Location where all data dependencies will be eventually collected
  DataObjIDColl m_dataDepKeys[NUM_ACCESS_MODES];

  bool m_explicitDepsCollected = false;

  // Places where we keep track of the inputs and outputs that were
  // ignored because they had an empty key
  DataObjIDColl m_ignoredDataDeps[NUM_ACCESS_MODES];

  static size_t accessToIndex( AccessMode access ) { return static_cast<size_t>( access ); }

  bool isNewDataDependency( const Gaudi::v2::DataHandle& handle ) const
  {
    auto index = accessToIndex( handle.access() );
    return m_dataDepKeys[index].find( handle.targetKey() ) == m_dataDepKeys[index].end();
  }

  bool isNewDataDependency( const Gaudi::v1::DataHandle& handle ) const
  {
    bool result = false;
    if ( handle.mode() & Gaudi::v1::DataHandle::Reader ) {
      auto index = accessToIndex( AccessMode::Read );
      result &= ( m_dataDepKeys[index].find( handle.fullKey() ) == m_dataDepKeys[index].end() );
    }
    if ( handle.mode() & Gaudi::v1::DataHandle::Writer ) {
      auto index = accessToIndex( AccessMode::Write );
      result &= ( m_dataDepKeys[index].find( handle.fullKey() ) == m_dataDepKeys[index].end() );
    }
    return result;
  }

  static const DataObjID& accessKey( const Gaudi::v2::DataHandle* handlePtr ) { return handlePtr->targetKey(); }

  static const DataObjID& accessKey( const DataObjID& key ) { return key; }

  static const DataObjID& accessKey( const Gaudi::v1::DataHandle* handlePtr ) { return handlePtr->fullKey(); }

  template <typename KeyHolder>
  static void extractKey( DataObjIDColl& validOutput, DataObjIDColl& ignoredOutput, const KeyHolder& holder )
  {
    const DataObjID& key = accessKey( holder );
    if ( !key.empty() ) {
      validOutput.insert( key );
    } else {
      ignoredOutput.insert( key );
    }
  }

  template <typename KeyHolderColl>
  static void extractKeys( DataObjIDColl& validOutput, DataObjIDColl& ignoredOutput, const KeyHolderColl& keyHolders )
  {
    validOutput.reserve( keyHolders.size() );
    for ( const auto& holder : keyHolders ) {
      extractKey( validOutput, ignoredOutput, holder );
    }
  }

  template <typename KeyHolderColl>
  void collectDependencies( const KeyHolderColl keyHolderArray[] )
  {
    for ( size_t i = 0; i < NUM_ACCESS_MODES; ++i ) {
      extractKeys( m_dataDepKeys[i], m_ignoredDataDeps[i], keyHolderArray[i] );
    }
  }

  void collectDependencies( const std::unordered_set<Gaudi::v1::DataHandle*> legacyHandles )
  {
    DataObjIDColl& validInputs    = m_dataDepKeys[accessToIndex( AccessMode::Read )];
    DataObjIDColl& validOutputs   = m_dataDepKeys[accessToIndex( AccessMode::Write )];
    DataObjIDColl& ignoredInputs  = m_ignoredDataDeps[accessToIndex( AccessMode::Read )];
    DataObjIDColl& ignoredOutputs = m_ignoredDataDeps[accessToIndex( AccessMode::Write )];

    for ( auto handle : legacyHandles ) {
      if ( handle->mode() & Gaudi::v1::DataHandle::Reader ) {
        extractKey( validInputs, ignoredInputs, handle );
      }
      if ( handle->mode() & Gaudi::v1::DataHandle::Writer ) {
        extractKey( validOutputs, ignoredOutputs, handle );
      }
    }
  }

  static void updateKey( Gaudi::v2::DataHandle* target, DataObjID&& key ) { target->setTargetKey( std::move( key ) ); }

  static void updateKey( DataObjID& target, DataObjID&& key ) { target = std::move( key ); }

  static void updateKey( Gaudi::v1::DataHandle* target, DataObjID&& key ) { target->setKey( std::move( key ) ); }

  template <typename KeyHolderColl>
  static void updateDependencies( KeyHolderColl& keyHolders, const DataObjIDMapping& keyMap )
  {
    for ( auto& holder : keyHolders ) {
      const DataObjID& oldKey    = accessKey( holder );
      auto             mappedKey = keyMap( oldKey );
      if ( mappedKey ) {
        updateKey( holder, *std::move( mappedKey ) );
      }
    }
  }

  static void updateDependencies( DataObjIDColl& keys, const DataObjIDMapping& keyMap )
  {
    DataObjIDColl result;
    result.reserve( keys.size() );
    for ( const auto& key : keys ) {
      result.emplace( keyMap( key ).value_or( key ) );
    }
    keys = std::move( result );
  }

  static void updateDependencies( Gaudi::Property<DataObjIDColl>& keys, const DataObjIDMapping& keyMap )
  {
    updateDependencies( keys.value(), keyMap );
  }

  template <typename KeyHolderColl>
  static void updateDependencies( KeyHolderColl keyHoldersArray[], const DataObjIDMapping& keyMap )
  {
    for ( size_t i = 0; i < NUM_ACCESS_MODES; ++i ) {
      updateDependencies( keyHoldersArray[i], keyMap );
    }
  }
};

#endif // !GAUDIKERNEL_DATAHANDLEHOLDERBASE