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