From ad2ca814b2e100c7da2b3371244f28c70baa1e32 Mon Sep 17 00:00:00 2001 From: "Robin.Mueller" Date: Mon, 28 Sep 2020 21:28:03 +0200 Subject: [PATCH] improved doc --- datapoollocal/LocalPoolDataSetBase.h | 24 +++++++++++++++++++----- datapoollocal/LocalPoolVariable.h | 13 ++++++------- datapoollocal/LocalPoolVariable.tpp | 6 +++--- datapoollocal/StaticLocalDataSet.h | 13 ++++++++----- 4 files changed, 36 insertions(+), 20 deletions(-) diff --git a/datapoollocal/LocalPoolDataSetBase.h b/datapoollocal/LocalPoolDataSetBase.h index 4f277123..d00af992 100644 --- a/datapoollocal/LocalPoolDataSetBase.h +++ b/datapoollocal/LocalPoolDataSetBase.h @@ -1,7 +1,6 @@ #ifndef FSFW_DATAPOOLLOCAL_LOCALPOOLDATASETBASE_H_ #define FSFW_DATAPOOLLOCAL_LOCALPOOLDATASETBASE_H_ - #include "HasLocalDataPoolIF.h" #include "../datapool/DataSetIF.h" #include "../datapool/PoolDataSetBase.h" @@ -16,15 +15,22 @@ class PeriodicHousekeepingHelper; * @brief The LocalDataSet class manages a set of locally checked out * variables for local data pools * @details + * Extends the PoolDataSetBase class for local data pools by introducing + * a validity state, a flag to mark the set as changed, and various other + * functions to make it usable by the LocalDataPoolManager class. + * * 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 local data pools, - * to ensure thread-safety. + * the commit call. The data set manages locking and freeing the local data + * pools, to ensure thread-safety. + * + * Pool variables can be added to the dataset by using the constructor + * argument of the pool variable or using the #registerVariable member function. * * An internal state manages usage of this class. Variables may only be - * registered before the read call is made, and the commit call only + * registered before any read call is made, and the commit call can only happen * after the read call. * * If pool variables are writable and not committed until destruction @@ -72,6 +78,7 @@ public: sid_t getSid() const; + /** SerializeIF overrides */ ReturnValue_t serialize(uint8_t** buffer, size_t* size, size_t maxSize, SerializeIF::Endianness streamEndianness) const override; ReturnValue_t deSerialize(const uint8_t** buffer, size_t *size, @@ -82,7 +89,7 @@ public: * Special version of the serilization function which appends a * validity buffer at the end. Each bit of this validity buffer * denotes whether the container data set entries are valid from left - * to right, MSB first. + * to right, MSB first. (length = ceil(N/8), N = number of pool variables) * @param buffer * @param size * @param maxSize @@ -142,6 +149,13 @@ protected: */ bool changed = false; + /** + * Specify whether the validity buffer is serialized too when serializing + * or deserializing the packet. Each bit of the validity buffer will + * contain the validity state of the pool variables from left to right. + * The size of validity buffer thus will be ceil(N / 8) with N = number of + * pool variables. + */ bool withValidityBuffer = true; /** diff --git a/datapoollocal/LocalPoolVariable.h b/datapoollocal/LocalPoolVariable.h index 6047342e..ec5c8cd1 100644 --- a/datapoollocal/LocalPoolVariable.h +++ b/datapoollocal/LocalPoolVariable.h @@ -1,12 +1,12 @@ -#ifndef FRAMEWORK_DATAPOOLLOCAL_LOCALPOOLVARIABLE_H_ -#define FRAMEWORK_DATAPOOLLOCAL_LOCALPOOLVARIABLE_H_ +#ifndef FSFW_DATAPOOLLOCAL_LOCALPOOLVARIABLE_H_ +#define FSFW_DATAPOOLLOCAL_LOCALPOOLVARIABLE_H_ + +#include "HasLocalDataPoolIF.h" +#include "LocalDataPoolManager.h" #include "../datapool/PoolVariableIF.h" #include "../datapool/DataSetIF.h" -#include "../datapoollocal/HasLocalDataPoolIF.h" -#include "../datapoollocal/LocalDataPoolManager.h" #include "../objectmanager/ObjectManagerIF.h" - #include "../serialize/SerializeAdapter.h" /** @@ -41,7 +41,6 @@ public: * @param dataSet The data set in which the variable shall register itself. * If nullptr, the variable is not registered. * @param setReadWriteMode Specify the read-write mode of the pool variable. - */ LocalPoolVar(lp_id_t poolId, HasLocalDataPoolIF* hkOwner, DataSetIF* dataSet = nullptr, @@ -175,4 +174,4 @@ using lp_float_t = LocalPoolVar; using lp_double_t = LocalPoolVar; -#endif +#endif /* FSFW_DATAPOOLLOCAL_LOCALPOOLVARIABLE_H_ */ diff --git a/datapoollocal/LocalPoolVariable.tpp b/datapoollocal/LocalPoolVariable.tpp index b47e602c..b0bdd7b9 100644 --- a/datapoollocal/LocalPoolVariable.tpp +++ b/datapoollocal/LocalPoolVariable.tpp @@ -1,7 +1,7 @@ -#ifndef FRAMEWORK_DATAPOOLLOCAL_LOCALPOOLVARIABLE_TPP_ -#define FRAMEWORK_DATAPOOLLOCAL_LOCALPOOLVARIABLE_TPP_ +#ifndef FSFW_DATAPOOLLOCAL_LOCALPOOLVARIABLE_TPP_ +#define FSFW_DATAPOOLLOCAL_LOCALPOOLVARIABLE_TPP_ -#ifndef FRAMEWORK_DATAPOOLLOCAL_LOCALPOOLVARIABLE_H_ +#ifndef FSFW_DATAPOOLLOCAL_LOCALPOOLVARIABLE_H_ #error Include LocalPoolVariable.h before LocalPoolVariable.tpp! #endif diff --git a/datapoollocal/StaticLocalDataSet.h b/datapoollocal/StaticLocalDataSet.h index 2f306898..a637e360 100644 --- a/datapoollocal/StaticLocalDataSet.h +++ b/datapoollocal/StaticLocalDataSet.h @@ -8,11 +8,14 @@ /** * @brief This local dataset type is created on the stack. * @details - * Size of data set specified as a constructor argument. It is recommended - * to use the default LocalDataSet of the dataset is constructed on the heap - * and the SharedLocalDataSet if it created on the heap and used by multiple - * other software objects. - * @tparam capacity + * This will is the primary data structure to organize pool variables into + * sets which can be accessed via the housekeeping service interface or + * which can be sent to other software objects. + * + * It is recommended to read the documentation of the LocalPoolDataSetBase + * class for more information on how this class works and how to use it. + * @tparam capacity Capacity of the static dataset, which is usually known + * beforehand. */ template class StaticLocalDataSet: public LocalPoolDataSetBase {