fsfw/datapool/PoolDataSetBase.h

#ifndef FSFW_DATAPOOL_POOLDATASETBASE_H_
#define FSFW_DATAPOOL_POOLDATASETBASE_H_

#include "PoolDataSetIF.h"
#include "PoolVariableIF.h"
#include "../ipc/MutexIF.h"

/**
 * @brief	The DataSetBase class manages a set of locally checked out variables.
 * @details
 * This class manages a list, where a set of local variables (or pool variables)
 * are registered. They are checked-out (i.e. their values are looked
 * up and copied) with the read call. After the user finishes working with the
 * pool variables, he can write back all variable values to the pool with
 * the commit call. The data set manages locking and freeing the data pool,
 * to ensure that all values are read and written back at once.
 *
 * An internal state manages usage of this class. Variables may only be
 * registered before the read call is made, and the commit call only
 * after the read call.
 *
 * If pool variables are writable and not committed until destruction
 * of the set, the DataSet class automatically sets the valid flag in the
 * data pool to invalid (without) changing the variable's value.
 *
 * The base class lockDataPool und unlockDataPool implementation are empty
 * and should be implemented to protect the underlying pool type.
 * @author	Bastian Baetz
 * @ingroup data_pool
 */
class PoolDataSetBase: public PoolDataSetIF,
		public SerializeIF,
		public HasReturnvaluesIF {
public:

	/**
	 * @brief	Creates an empty dataset. Use registerVariable or
	 * 			supply a pointer to this dataset to PoolVariable
	 * 			initializations to register pool variables.
	 */
	PoolDataSetBase(PoolVariableIF** registeredVariablesArray,
	        const size_t maxFillCount);
	virtual~ PoolDataSetBase();

	/**
	 * @brief	The read call initializes reading out all registered variables.
	 * 			It is mandatory to call commit after every read call!
	 * @details
	 *
	 * TODO: Write RAII helper so user can not forget to call commit anymore.
	 *
	 * It iterates through the list of registered variables and calls all read()
	 * functions of the registered pool variables (which read out their values
	 * from the data pool) which are not write-only.
	 * In case of an error (e.g. a wrong data type, or an invalid data pool id),
	 * the operation is aborted and @c INVALID_PARAMETER_DEFINITION returned.
	 *
	 * The data pool is locked during the whole read operation and
	 * freed afterwards. It is mandatory to call commit after a read call,
	 * even if the read operation is not successful!
	 * @return
	 * - @c RETURN_OK if all variables were read successfully.
	 * - @c INVALID_PARAMETER_DEFINITION if a pool entry does not exist or there
	 *      is a type conflict.
	 * - @c SET_WAS_ALREADY_READ if read() is called twice without calling
	 *      commit() in between
	 */
	virtual ReturnValue_t read(uint32_t lockTimeout =
			MutexIF::BLOCKING) override;
	/**
	 * @brief	The commit call initializes writing back the registered variables.
	 * @details
	 * It iterates through the list of registered variables and calls the
	 * commit() method of the remaining registered variables (which write back
	 * their values to the pool).
	 *
	 * The data pool is locked during the whole commit operation and
	 * freed afterwards. The state changes to "was committed" after this operation.
	 *
	 * If the set does contain at least one variable which is not write-only
	 * commit() can only be called after read(). If the set only contains
	 * variables which are write only, commit() can be called without a
	 * preceding read() call. Every read call must be followed by a commit call!
	 * @return	- @c RETURN_OK if all variables were read successfully.
	 * 			- @c COMMITING_WITHOUT_READING if set was not read yet and
	 * 			  contains non write-only variables
	 */
	virtual ReturnValue_t commit(uint32_t lockTimeout =
			MutexIF::BLOCKING) override;

	/**
	 * Register the passed pool variable instance into the data set.
	 * @param variable
	 * @return
	 */
	virtual ReturnValue_t registerVariable( PoolVariableIF* variable) override;

	/**
	 * Provides the means to lock the underlying data structure to ensure
	 * thread-safety. Default implementation is empty
	 * @return Always returns -@c RETURN_OK
	 */
	virtual ReturnValue_t lockDataPool(uint32_t timeoutMs =
			MutexIF::BLOCKING) override;
	/**
	 * Provides the means to unlock the underlying data structure to ensure
	 * thread-safety. Default implementation is empty
	 * @return Always returns -@c RETURN_OK
	 */
	virtual ReturnValue_t unlockDataPool() override;

	virtual uint16_t getFillCount() const;

	/* SerializeIF implementations */
	virtual ReturnValue_t serialize(uint8_t** buffer, size_t* size,
				const size_t maxSize,
				SerializeIF::Endianness streamEndianness) const override;
	virtual size_t getSerializedSize() const override;
	virtual ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size,
	        SerializeIF::Endianness streamEndianness) override;

protected:

	/**
	 * Can be used to individually protect every read and commit call.
	 * @param protectEveryReadCommit
	 * @param mutexTimeout
	 */
	void setReadCommitProtectionBehaviour(bool protectEveryReadCommit,
			uint32_t mutexTimeout = 20);

	/**
	 * @brief	The fill_count attribute ensures that the variables
	 * 			register in the correct array position and that the maximum
	 * 			number of variables is not exceeded.
	 */
	uint16_t fillCount = 0;
	/**
	 * States of the seet.
	 */
	enum class States {
		STATE_SET_UNINITIALISED, //!< DATA_SET_UNINITIALISED
		STATE_SET_WAS_READ     //!< DATA_SET_WAS_READ
	};
	/**
	 * @brief	state manages the internal state of the data set,
	 *          which is important e.g. for the behavior on destruction.
	 */
	States state = States::STATE_SET_UNINITIALISED;

	/**
	 * @brief	This array represents all pool variables registered in this set.
	 * Child classes can use a static or dynamic container to create
	 * an array of registered variables and assign the first entry here.
	 */
	PoolVariableIF** registeredVariables = nullptr;
	const size_t maxFillCount = 0;

	void setContainer(PoolVariableIF** variablesContainer);

private:
	bool protectEveryReadCommitCall = false;
	uint32_t mutexTimeout = 20;

	ReturnValue_t readVariable(uint16_t count);
	void handleAlreadyReadDatasetCommit(uint32_t lockTimeout);
	ReturnValue_t handleUnreadDatasetCommit(uint32_t lockTimeout);
};

#endif /* FSFW_DATAPOOL_POOLDATASETBASE_H_ */