src/gromacs/analysisdata/datamodulemanager.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013,2014 by the GROMACS development team.
   5  * Copyright (c) 2015,2019,2020, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \libinternal \file
  37  * \brief
  38  * Declares gmx::AnalysisDataModuleManager.
  39  *
  40  * \author Teemu Murtola <teemu.murtola@gmail.com>
  41  * \inlibraryapi
  42  * \ingroup module_analysisdata
  43  */
  44 #ifndef GMX_ANALYSISDATA_DATAMODULEMANAGER_H
  45 #define GMX_ANALYSISDATA_DATAMODULEMANAGER_H
  46
  47 #include "gromacs/analysisdata/abstractdata.h"
  48 #include "gromacs/utility/classhelpers.h"
  49
  50 namespace gmx
  51 {
  52
  53 class AnalysisDataParallelOptions;
  54
  55 /*! \libinternal \brief
  56  * Encapsulates handling of data modules attached to AbstractAnalysisData.
  57  *
  58  * See IAnalysisDataModule and \ref module_analysisdata for more
  59  * details on the notifications and the order in which they should be raised.
  60  *
  61  * \inlibraryapi
  62  * \ingroup module_analysisdata
  63  */
  64 class AnalysisDataModuleManager
  65 {
  66 public:
  67     /*! \brief
  68      * Identifies data properties to check with data modules.
  69      *
  70      * \see IAnalysisDataModule::Flag
  71      */
  72     enum DataProperty
  73     {
  74         eMultipleDataSets, //!< Data has multiple data sets.
  75         eMultipleColumns,  //!< Data has multiple columns.
  76         eMultipoint,       //!< Data is multipoint.
  77         eDataPropertyNR    //!< Number of properties; for internal use only.
  78     };
  79
  80     AnalysisDataModuleManager();
  81     ~AnalysisDataModuleManager();
  82
  83     /*! \brief
  84      * Allows the manager to check modules for compatibility with the data.
  85      *
  86      * \throws  APIError if any data module already added is not compatible
  87      *      with the new setting.
  88      *
  89      * Does two things: checks any modules already attached to the data and
  90      * throws if any of them is not compatible, and stores the property
  91      * to check modules attached in the future.
  92      *
  93      * Strong exception safety.
  94      */
  95     void dataPropertyAboutToChange(DataProperty property, bool bSet);
  96
  97     /*! \brief
  98      * Whether there are modules that do not support parallel processing.
  99      *
 100      * Must not be called before notifyDataStart()/notifyParallelDataStart().
 101      * If notifyDataStart() has been called, returns true if there are any
 102      * modules (all modules are treated as serial).
 103      *
 104      * Does not throw.
 105      */
 106     bool hasSerialModules() const;
 107
 108     /*! \brief
 109      * Adds a module to process the data.
 110      *
 111      * \param     data    Data object to add the module to.
 112      * \param     module  Module to add.
 113      * \throws    std::bad_alloc if out of memory.
 114      * \throws    APIError if
 115      *      - \p module is not compatible with the data object
 116      *      - data has already been added to the data object and everything
 117      *        is not available through getDataFrame().
 118      * \throws    unspecified Any exception thrown by \p module in its
 119      *      notification methods (if data has been added).
 120      *
 121      * \see AbstractAnalysisData::addModule()
 122      */
 123     void addModule(AbstractAnalysisData* data, const AnalysisDataModulePointer& module);
 124     /*! \brief
 125      * Applies a module to process data that is ready.
 126      *
 127      * \param     data    Data object to apply the module to.
 128      * \param     module  Module to apply.
 129      * \throws    APIError in same situations as addModule().
 130      * \throws    unspecified Any exception thrown by \p module in its
 131      *      notification methods.
 132      *
 133      * \see AbstractAnalysisData::applyModule()
 134      */
 135     void applyModule(AbstractAnalysisData* data, IAnalysisDataModule* module);
 136
 137     /*! \brief
 138      * Notifies attached modules of the start of serial data.
 139      *
 140      * \param   data  Data object that is starting.
 141      * \throws  APIError if any attached data module is not compatible.
 142      * \throws  unspecified Any exception thrown by attached data modules
 143      *      in IAnalysisDataModule::dataStarted().
 144      *
 145      * Should be called once, after data properties have been set with
 146      * the methods in AbstractAnalysisData, and before any other
 147      * notification methods.
 148      * The caller should be prepared for requestStorage() calls to \p data
 149      * from the attached modules.
 150      *
 151      * \p data should typically be \c this when calling from a class
 152      * derived from AbstractAnalysisData.
 153      *
 154      * This method initializes all modules for serial processing by calling
 155      * IAnalysisDataModule::dataStarted().
 156      */
 157     void notifyDataStart(AbstractAnalysisData* data);
 158     /*! \brief
 159      * Notifies attached modules of the start of parallel data.
 160      *
 161      * \param     data    Data object that is starting.
 162      * \param[in] options Parallelization properties of the input data.
 163      * \throws  APIError if any attached data module is not compatible.
 164      * \throws  unspecified Any exception thrown by attached data modules
 165      *      in IAnalysisDataModule::parallelDataStarted().
 166      *
 167      * Can be called instead of notifyDataStart() if \p data supports
 168      * non-sequential creation of frames.  Works as notifyDataStart(),
 169      * but instead calls IAnalysisDataModule::parallelDataStarted()
 170      * and records whether the module supports the parallel mode.
 171      * Subsequent notification calls then notify the modules according to
 172      * the mode they accept.
 173      *
 174      * See notifyDataStart() for general constraints.
 175      */
 176     void notifyParallelDataStart(AbstractAnalysisData* data, const AnalysisDataParallelOptions& options);
 177     /*! \brief
 178      * Notifies attached serial modules of the start of a frame.
 179      *
 180      * \param[in] header  Header information for the frame that is starting.
 181      * \throws    unspecified Any exception thrown by attached data modules
 182      *      in IAnalysisDataModule::frameStarted().
 183      *
 184      * Should be called once for each frame, before notifyPointsAdd() calls
 185      * for that frame.
 186      */
 187     void notifyFrameStart(const AnalysisDataFrameHeader& header) const;
 188     /*! \brief
 189      * Notifies attached parallel modules of the start of a frame.
 190      *
 191      * \param[in] header  Header information for the frame that is starting.
 192      * \throws    unspecified Any exception thrown by attached data modules
 193      *      in IAnalysisDataModule::frameStarted().
 194      *
 195      * If notifyParallelDataStart() has been called, should be called once
 196      * for each frame, before notifyParallelPointsAdd() calls for that
 197      * frame.
 198      * It is allowed to call this method in any order for the frames, but
 199      * should be called exactly once for each frame.
 200      */
 201     void notifyParallelFrameStart(const AnalysisDataFrameHeader& header) const;
 202     /*! \brief
 203      * Notifies attached serial modules of the addition of points to the
 204      * current frame.
 205      *
 206      * \param[in] points  Set of points added (also provides access to
 207      *      frame-level data).
 208      * \throws    APIError if any attached data module is not compatible.
 209      * \throws    unspecified Any exception thrown by attached data modules
 210      *      in IAnalysisDataModule::pointsAdded().
 211      *
 212      * Can be called zero or more times for each frame.
 213      * The caller should ensure that any column occurs at most once in the
 214      * calls, unless the data is multipoint.
 215      * For efficiency reasons, calls to this method should be aggregated
 216      * whenever possible, i.e., it's better to handle multiple columns or
 217      * even the whole frame in a single call rather than calling the method
 218      * for each column separately.
 219      */
 220     void notifyPointsAdd(const AnalysisDataPointSetRef& points) const;
 221     /*! \brief
 222      * Notifies attached parallel modules of the addition of points to a frame.
 223      *
 224      * \param[in] points  Set of points added (also provides access to
 225      *      frame-level data).
 226      * \throws    APIError if any attached data module is not compatible.
 227      * \throws    unspecified Any exception thrown by attached data modules
 228      *      in IAnalysisDataModule::pointsAdded().
 229      *
 230      * See notifyPointsAdd() for information on the structure of the point
 231      * sets.
 232      */
 233     void notifyParallelPointsAdd(const AnalysisDataPointSetRef& points) const;
 234     /*! \brief
 235      * Notifies attached serial modules of the end of a frame.
 236      *
 237      * \param[in] header  Header information for the frame that is ending.
 238      * \throws    unspecified Any exception thrown by attached data modules
 239      *      in IAnalysisDataModule::frameFinished().
 240      *
 241      * Should be called once for each call of notifyFrameStart(), after any
 242      * notifyPointsAdd() calls for the frame.
 243      * \p header should be identical to that used in the corresponding
 244      * notifyFrameStart() call.
 245      *
 246      * This method also notifies parallel modules about serial end of frame.
 247      */
 248     void notifyFrameFinish(const AnalysisDataFrameHeader& header) const;
 249     /*! \brief
 250      * Notifies attached parallel modules of the end of a frame.
 251      *
 252      * \param[in] header  Header information for the frame that is ending.
 253      * \throws    unspecified Any exception thrown by attached data modules
 254      *      in IAnalysisDataModule::frameFinished().
 255      *
 256      * Should be called once for each call of notifyParallelFrameStart(),
 257      * after any notifyParallelPointsAdd() calls for the frame.
 258      * \p header should be identical to that used in the corresponding
 259      * notifyParallelFrameStart() call.
 260      */
 261     void notifyParallelFrameFinish(const AnalysisDataFrameHeader& header) const;
 262     /*! \brief
 263      * Notifies attached modules of the end of data.
 264      *
 265      * \throws    unspecified Any exception thrown by attached data modules
 266      *      in IAnalysisDataModule::dataFinished().
 267      *
 268      * Should be called once, after all the other notification calls.
 269      */
 270     void notifyDataFinish() const;
 271
 272 private:
 273     class Impl;
 274
 275     PrivateImplPointer<Impl> impl_;
 276 };
 277
 278 } // namespace gmx
 279
 280 #endif