diff --git a/MathLib/LinAlg/MatrixProviderUser.h b/MathLib/LinAlg/MatrixProviderUser.h new file mode 100644 index 0000000000000000000000000000000000000000..72145372c9d56fa6e4a9281310c5c260dbef603c --- /dev/null +++ b/MathLib/LinAlg/MatrixProviderUser.h @@ -0,0 +1,131 @@ +/** + * \copyright + * Copyright (c) 2012-2016, OpenGeoSys Community (http://www.opengeosys.org) + * Distributed under a Modified BSD License. + * See accompanying file LICENSE.txt or + * http://www.opengeosys.org/project/license + * + */ + +#ifndef MATHLIB_MATRIX_PROVIDER_USER_H +#define MATHLIB_MATRIX_PROVIDER_USER_H + +#include <cstddef> + +namespace MathLib +{ + +struct MatrixSpecifications +{ + std::size_t const nrows; + std::size_t const ncols; +}; + +class MatrixSpecificationsProvider +{ +public: + virtual MatrixSpecifications getMatrixSpecifications() const = 0; + + virtual ~MatrixSpecificationsProvider() = default; +}; + + +/*! Manages storage for vectors. + * + * This interface provides storage management semantics for vectors, which + * can be acquired at a certain point in time, be released later on and + * be acquired again etc. + * + * "Released" means that the caller indicates, that he currently does not need + * that \c Vector instance, i.e, Either it is not needed anymore for the entire + * program run, or it is temporarily not needed, but might be aquired again + * later on. Thereby the implementation of this interface can decide, whether + * the storage for the specific vector can be freed or reused in the meantime. + * + * All get-methods of this class come in two variants: One with an \c id argument, + * and one without. The latter makes it possible to temporarily release a vector + * during the program run and re-acquire it again. The former variant is intended + * as a short-cut that simplifies vector acquisition for callers that will use + * the same vector throughout all of their lifetime without releasing it + * intermediately. + * + * \attention + * The first time a vector is acquired by a method with \c id argument, the \c id + * has to be initialized with zero. The respective method then will set the \c id + * to the specific \c id of the returned vector. + */ +template<typename Vector> +class VectorProvider +{ +public: + using MSP = MatrixSpecificationsProvider; + + //! Get an uninitialized vector. + virtual Vector& getVector() = 0; + + //! Get an uninitialized vector with the given \c id. + virtual Vector& getVector(std::size_t& id) = 0; + + //! Get a copy of \c x. + virtual Vector& getVector(Vector const& x) = 0; + + //! Get a copy of \c x in the storage of the vector with the given \c id. + virtual Vector& getVector(Vector const& x, std::size_t& id) = 0; + + //! Get a vector according to the given specifications. + virtual Vector& getVector(MSP const& msp) = 0; + + //! Get a vector according to the given specifications in the storage + //! of the vector with the given \c id. + virtual Vector& getVector(MSP const& msp, std::size_t& id) = 0; + + //! Release the given vector. + //! + //! \pre \c x must have been acquired before, i.e., you must not call this + //! method twice in a row in the same \c x! + virtual void releaseVector(Vector const& x) = 0; + + virtual ~VectorProvider() = default; +}; + +/*! Manages storage for matrices. + * + * This the matrix-analog of VectorProvider. The same notes apply to this class. + */ +template<typename Matrix> +class MatrixProvider +{ +public: + using MSP = MatrixSpecificationsProvider; + + //! Get an uninitialized matrix. + virtual Matrix& getMatrix() = 0; + + //! Get an uninitialized matrix with the given \c id. + virtual Matrix& getMatrix(std::size_t& id) = 0; + + //! Get a copy of \c A. + virtual Matrix& getMatrix(Matrix const& A) = 0; + + //! Get a copy of \c A in the storage of the matrix with the given \c id. + virtual Matrix& getMatrix(Matrix const& A, std::size_t& id) = 0; + + //! Get a matrix according to the given specifications. + virtual Matrix& getMatrix(MSP const& msp) = 0; + + //! Get a matrix according to the given specifications in the storage + //! of the matrix with the given \c id. + virtual Matrix& getMatrix(MSP const& msp, std::size_t& id) = 0; + + //! Release the given matrix. + //! + //! \pre \c A must have been acquired before, i.e., you must not call this + //! method twice in a row in the same \c A! + virtual void releaseMatrix(Matrix const& A) = 0; + + virtual ~MatrixProvider() = default; +}; + +} // namespace MathLib + +#endif // MATHLIB_MATRIX_PROVIDER_USER_H