Gromacs  2022.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions
gmx::AnalysisDataStorage Class Reference

#include <gromacs/analysisdata/datastorage.h>

Description

Helper class that implements storage of data.

This class implements a standard way of storing data to avoid implementing storage in each class derived from AbstractAnalysisData separately. To use this class in a class derived from AbstractAnalysisData, a member variable of this type should be declared and the pure virtual methods forwarded to frameCount(), tryGetDataFrame() and requestStorage(). Storage properties should be set up, and then startDataStorage() or startParallelDataStorage() called. New frames can then be added using startFrame(), currentFrame(), finishFrame(), and finishFrameSerial() methods (the last is only necessary if startParallelDataStorage() is used). When all frames are ready, finishDataStorage() must be called. These methods (and AnalysisDataStorageFrame::finishPointSet()) take the responsibility of calling all the notification methods in AnalysisDataModuleManager,

Todo:
Proper multi-threaded implementation.

Public Member Functions

 AnalysisDataStorage ()
 Constructs a storage object.
 
int frameCount () const
 Returns the number of ready frames. More...
 
AnalysisDataFrameRef tryGetDataFrame (int index) const
 Implements access to data frames. More...
 
bool requestStorage (int nframes)
 Implements storage requests. More...
 
void startDataStorage (AbstractAnalysisData *data, AnalysisDataModuleManager *modules)
 Start storing data. More...
 
void startParallelDataStorage (AbstractAnalysisData *data, AnalysisDataModuleManager *modules, const AnalysisDataParallelOptions &options)
 Start storing data in parallel. More...
 
AnalysisDataStorageFramestartFrame (const AnalysisDataFrameHeader &header)
 Starts storing a new frame. More...
 
AnalysisDataStorageFramestartFrame (int index, real x, real dx)
 Convenience method to start storing a new frame. More...
 
AnalysisDataStorageFramecurrentFrame (int index)
 Obtains a frame object for an in-progress frame. More...
 
void finishFrame (int index)
 Convenience method for finishing a data frame. More...
 
void finishFrameSerial (int index)
 Performs in-order sequential processing for a data frame. More...
 
void finishDataStorage ()
 Finishes storing data. More...
 

Member Function Documentation

AnalysisDataStorageFrame & gmx::AnalysisDataStorage::currentFrame ( int  index)

Obtains a frame object for an in-progress frame.

Parameters
[in]indexFrame index.
Return values
Frameobject corresponding to index.

startFrame() should have been called for the frame with index index, and finishFrame() should not yet have been called. Returns the same object as returned by the original startFrame() call for the same index.

Does not throw.

void gmx::AnalysisDataStorage::finishDataStorage ( )

Finishes storing data.

Calls AnalysisDataModuleManager::notifyDataFinish(), and throws any exceptions this method throws.

void gmx::AnalysisDataStorage::finishFrame ( int  index)

Convenience method for finishing a data frame.

Parameters
[in]indexFrame index.

Identical to currentFrame(index).finishFrame().

See Also
AnalysisDataStorageFrame::finishFrame()
void gmx::AnalysisDataStorage::finishFrameSerial ( int  index)

Performs in-order sequential processing for a data frame.

Parameters
[in]indexFrame index.

If startParallelDataStorage() has been called with options that indicate parallelism, this method must be called after finishFrame(index) (or the equivalent call in AnalysisDataStorageFrame), such that it is called in the correct order sequentially for each frame.

If there is no parallelism, this method does nothing; the equivalent processing is done already during finishFrame().

int gmx::AnalysisDataStorage::frameCount ( ) const

Returns the number of ready frames.

This method is designed such that calls to AbstractAnalysisData::frameCount() can be directly forwarded to this method. See that method for more documentation.

If this method returns N, this means that the first N frames have all been finished.

See Also
AbstractAnalysisData::frameCount()
bool gmx::AnalysisDataStorage::requestStorage ( int  nframes)

Implements storage requests.

This method is designed such that calls to AbstractAnalysisData::requestStorageInternal() can be directly forwarded to this method. See that method for more documentation.

See Also
AbstractAnalysisData::requestStorageInternal()
void gmx::AnalysisDataStorage::startDataStorage ( AbstractAnalysisData data,
AnalysisDataModuleManager modules 
)

Start storing data.

Parameters
[in]dataAbstractAnalysisData object containing this storage.
modulesModule manager for data.
Exceptions
std::bad_allocif storage allocation fails.

Typically called as startDataStorage(this, &moduleManager()) from a member of data when the data is ready to be started. The storage object will take responsibility of calling all module notification methods in AnalysisDataModuleManager using modules.

Lifetime of data and modules must exceed the lifetime of the storage object (typically, the storage object will be a member in data).

Calls AnalysisDataModuleManager::notifyDataStart(), and throws any exceptions this method throws.

AnalysisDataStorageFrame & gmx::AnalysisDataStorage::startFrame ( const AnalysisDataFrameHeader header)

Starts storing a new frame.

Parameters
[in]headerHeader for the new frame.
Return values
Frameobject corresponding to the started frame.
Exceptions
std::bad_allocif storage reallocation fails (only possible if storage of all frames has been requested).
APIErrorif frame is too far in the future.

The returned object will be valid until the corresponding finishFrame() call.

Must be called exactly once for each frame index.

Currently, the implementation only works if the new frame is not too far in the future: If i is the index of the last frame such that all frames from 0, ..., i have been finished, then header().index() should be at most parallelizationFactor larger than i, where parallelizationFactor is the parallelization factor passed to setParallelOptions(). Throws APIError if this constraint is violated.

Calls AnalysisDataModuleManager::notifyFrameStart() (in certain cases) and AnalysisDataModuleManager::notifyParallelFrameStart(), and throws any exceptions these methods throw.

AnalysisDataStorageFrame & gmx::AnalysisDataStorage::startFrame ( int  index,
real  x,
real  dx 
)

Convenience method to start storing a new frame.

Identical to startFrame(AnalysisDataFrameHeader(index, x, dx));

void gmx::AnalysisDataStorage::startParallelDataStorage ( AbstractAnalysisData data,
AnalysisDataModuleManager modules,
const AnalysisDataParallelOptions options 
)

Start storing data in parallel.

Parameters
[in]dataAbstractAnalysisData object containing this storage.
[in]optionsParallelization options to use.
modulesModule manager for data.
Exceptions
std::bad_allocif storage allocation fails.

Should be called instead of startDataStorage() if the data will be produced in parallel. Works as startDataStorage(), but additionally initializes the storage and the attached modules to prepare for out-of-order data frames.

Calls AnalysisDataModuleManager::notifyParallelDataStart(), and throws any exceptions this method throws.

AnalysisDataFrameRef gmx::AnalysisDataStorage::tryGetDataFrame ( int  index) const

Implements access to data frames.

This method is designed such that calls to AbstractAnalysisData::tryGetDataFrameInternal() can be directly forwarded to this method. See that method for more documentation.

A valid reference for a frame will be returned after finishFrame() has been called for that frame.

See Also
AbstractAnalysisData::tryGetDataFrameInternal()

The documentation for this class was generated from the following files: