#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...

AnalysisDataStorageFrame &	startFrame (const AnalysisDataFrameHeader &header)
	Starts storing a new frame. More...

AnalysisDataStorageFrame &	startFrame (int index, real x, real dx)
	Convenience method to start storing a new frame. More...

AnalysisDataStorageFrame &	currentFrame (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] index Frame index.

Return values

Frame object 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] index Frame 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] index Frame 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]	data	AbstractAnalysisData object containing this storage.
	modules	Module manager for `data`.

Exceptions

std::bad_alloc if 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] header Header for the new frame.

Return values

Frame object corresponding to the started frame.

Exceptions

std::bad_alloc	if storage reallocation fails (only possible if storage of all frames has been requested).
APIError	if 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]	data	AbstractAnalysisData object containing this storage.
[in]	options	Parallelization options to use.
	modules	Module manager for `data`.

Exceptions

std::bad_alloc if 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:

src/gromacs/analysisdata/datastorage.h
src/gromacs/analysisdata/datastorage.cpp

Description

Public Member Functions

Member Function Documentation