2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2013,2014 by the GROMACS development team.
5 * Copyright (c) 2015,2019,2020,2021, 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.
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.
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.
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.
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.
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.
36 /*! \libinternal \file
38 * Declares gmx::AnalysisDataModuleManager.
40 * \author Teemu Murtola <teemu.murtola@gmail.com>
42 * \ingroup module_analysisdata
44 #ifndef GMX_ANALYSISDATA_DATAMODULEMANAGER_H
45 #define GMX_ANALYSISDATA_DATAMODULEMANAGER_H
49 #include "gromacs/analysisdata/abstractdata.h"
54 class AnalysisDataParallelOptions;
56 /*! \libinternal \brief
57 * Encapsulates handling of data modules attached to AbstractAnalysisData.
59 * See IAnalysisDataModule and \ref module_analysisdata for more
60 * details on the notifications and the order in which they should be raised.
63 * \ingroup module_analysisdata
65 class AnalysisDataModuleManager
69 * Identifies data properties to check with data modules.
71 * \see IAnalysisDataModule::Flag
75 eMultipleDataSets, //!< Data has multiple data sets.
76 eMultipleColumns, //!< Data has multiple columns.
77 eMultipoint, //!< Data is multipoint.
78 eDataPropertyNR //!< Number of properties; for internal use only.
81 AnalysisDataModuleManager();
82 ~AnalysisDataModuleManager();
85 * Allows the manager to check modules for compatibility with the data.
87 * \throws APIError if any data module already added is not compatible
88 * with the new setting.
90 * Does two things: checks any modules already attached to the data and
91 * throws if any of them is not compatible, and stores the property
92 * to check modules attached in the future.
94 * Strong exception safety.
96 void dataPropertyAboutToChange(DataProperty property, bool bSet);
99 * Whether there are modules that do not support parallel processing.
101 * Must not be called before notifyDataStart()/notifyParallelDataStart().
102 * If notifyDataStart() has been called, returns true if there are any
103 * modules (all modules are treated as serial).
107 bool hasSerialModules() const;
110 * Adds a module to process the data.
112 * \param data Data object to add the module to.
113 * \param module Module to add.
114 * \throws std::bad_alloc if out of memory.
115 * \throws APIError if
116 * - \p module is not compatible with the data object
117 * - data has already been added to the data object and everything
118 * is not available through getDataFrame().
119 * \throws unspecified Any exception thrown by \p module in its
120 * notification methods (if data has been added).
122 * \see AbstractAnalysisData::addModule()
124 void addModule(AbstractAnalysisData* data, const AnalysisDataModulePointer& module);
126 * Applies a module to process data that is ready.
128 * \param data Data object to apply the module to.
129 * \param module Module to apply.
130 * \throws APIError in same situations as addModule().
131 * \throws unspecified Any exception thrown by \p module in its
132 * notification methods.
134 * \see AbstractAnalysisData::applyModule()
136 void applyModule(AbstractAnalysisData* data, IAnalysisDataModule* module);
139 * Notifies attached modules of the start of serial data.
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 IAnalysisDataModule::dataStarted().
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.
152 * \p data should typically be \c this when calling from a class
153 * derived from AbstractAnalysisData.
155 * This method initializes all modules for serial processing by calling
156 * IAnalysisDataModule::dataStarted().
158 void notifyDataStart(AbstractAnalysisData* data);
160 * Notifies attached modules of the start of parallel data.
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 IAnalysisDataModule::parallelDataStarted().
168 * Can be called instead of notifyDataStart() if \p data supports
169 * non-sequential creation of frames. Works as notifyDataStart(),
170 * but instead calls IAnalysisDataModule::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.
175 * See notifyDataStart() for general constraints.
177 void notifyParallelDataStart(AbstractAnalysisData* data, const AnalysisDataParallelOptions& options);
179 * Notifies attached serial modules of the start of a frame.
181 * \param[in] header Header information for the frame that is starting.
182 * \throws unspecified Any exception thrown by attached data modules
183 * in IAnalysisDataModule::frameStarted().
185 * Should be called once for each frame, before notifyPointsAdd() calls
188 void notifyFrameStart(const AnalysisDataFrameHeader& header) const;
190 * Notifies attached parallel modules of the start of a frame.
192 * \param[in] header Header information for the frame that is starting.
193 * \throws unspecified Any exception thrown by attached data modules
194 * in IAnalysisDataModule::frameStarted().
196 * If notifyParallelDataStart() has been called, should be called once
197 * for each frame, before notifyParallelPointsAdd() calls for that
199 * It is allowed to call this method in any order for the frames, but
200 * should be called exactly once for each frame.
202 void notifyParallelFrameStart(const AnalysisDataFrameHeader& header) const;
204 * Notifies attached serial modules of the addition of points to the
207 * \param[in] points Set of points added (also provides access to
209 * \throws APIError if any attached data module is not compatible.
210 * \throws unspecified Any exception thrown by attached data modules
211 * in IAnalysisDataModule::pointsAdded().
213 * Can be called zero or more times for each frame.
214 * The caller should ensure that any column occurs at most once in the
215 * calls, unless the data is multipoint.
216 * For efficiency reasons, calls to this method should be aggregated
217 * whenever possible, i.e., it's better to handle multiple columns or
218 * even the whole frame in a single call rather than calling the method
219 * for each column separately.
221 void notifyPointsAdd(const AnalysisDataPointSetRef& points) const;
223 * Notifies attached parallel modules of the addition of points to a frame.
225 * \param[in] points Set of points added (also provides access to
227 * \throws APIError if any attached data module is not compatible.
228 * \throws unspecified Any exception thrown by attached data modules
229 * in IAnalysisDataModule::pointsAdded().
231 * See notifyPointsAdd() for information on the structure of the point
234 void notifyParallelPointsAdd(const AnalysisDataPointSetRef& points) const;
236 * Notifies attached serial modules of the end of a frame.
238 * \param[in] header Header information for the frame that is ending.
239 * \throws unspecified Any exception thrown by attached data modules
240 * in IAnalysisDataModule::frameFinished().
242 * Should be called once for each call of notifyFrameStart(), after any
243 * notifyPointsAdd() calls for the frame.
244 * \p header should be identical to that used in the corresponding
245 * notifyFrameStart() call.
247 * This method also notifies parallel modules about serial end of frame.
249 void notifyFrameFinish(const AnalysisDataFrameHeader& header) const;
251 * Notifies attached parallel modules of the end of a frame.
253 * \param[in] header Header information for the frame that is ending.
254 * \throws unspecified Any exception thrown by attached data modules
255 * in IAnalysisDataModule::frameFinished().
257 * Should be called once for each call of notifyParallelFrameStart(),
258 * after any notifyParallelPointsAdd() calls for the frame.
259 * \p header should be identical to that used in the corresponding
260 * notifyParallelFrameStart() call.
262 void notifyParallelFrameFinish(const AnalysisDataFrameHeader& header) const;
264 * Notifies attached modules of the end of data.
266 * \throws unspecified Any exception thrown by attached data modules
267 * in IAnalysisDataModule::dataFinished().
269 * Should be called once, after all the other notification calls.
271 void notifyDataFinish() const;
276 std::unique_ptr<Impl> impl_;