added documentation to assembly base

This commit is contained in:
Robin Müller 2020-08-07 19:21:47 +02:00
parent 66039bd3fe
commit 1a118fe215
3 changed files with 65 additions and 35 deletions

View File

@ -165,9 +165,8 @@ ReturnValue_t AssemblyBase::checkChildrenState() {
} }
ReturnValue_t AssemblyBase::checkChildrenStateOff() { ReturnValue_t AssemblyBase::checkChildrenStateOff() {
for (std::map<object_id_t, ChildInfo>::iterator iter = childrenMap.begin(); for (const auto& childIter: childrenMap) {
iter != childrenMap.end(); iter++) { if (checkChildOff(childIter.first) != RETURN_OK) {
if (checkChildOff(iter->first) != RETURN_OK) {
return NOT_ENOUGH_CHILDREN_IN_CORRECT_STATE; return NOT_ENOUGH_CHILDREN_IN_CORRECT_STATE;
} }
} }

View File

@ -1,10 +1,30 @@
#ifndef ASSEMBLYBASE_H_ #ifndef FRAMEWORK_DEVICEHANDLERS_ASSEMBLYBASE_H_
#define ASSEMBLYBASE_H_ #define FRAMEWORK_DEVICEHANDLERS_ASSEMBLYBASE_H_
#include <framework/container/FixedArrayList.h> #include <framework/container/FixedArrayList.h>
#include <framework/devicehandlers/DeviceHandlerBase.h> #include <framework/devicehandlers/DeviceHandlerBase.h>
#include <framework/subsystem/SubsystemBase.h> #include <framework/subsystem/SubsystemBase.h>
/**
* @brief Base class to implement reconfiguration and failure handling for
* redundant devices by monitoring their modes health states.
* @details
* Documentation: Dissertation Baetz p.156, 157.
*
* This class reduces the complexity of controller components which would
* otherwise be needed for the handling of redundant devices.
*
* The template class monitors mode and health state of its children
* and checks availability of devices on every detected change.
* AssemblyBase does not implement any redundancy logic by itself, but provides
* adaptation points for implementations to do so. Since most monitoring
* activities rely on mode and health state only and are therefore
* generic, it is sufficient for subclasses to provide:
*
* 1. check logic when active-> checkChildrenStateOn
* 2. transition logic to change the mode -> commandChildren
*
*/
class AssemblyBase: public SubsystemBase { class AssemblyBase: public SubsystemBase {
public: public:
static const uint8_t INTERFACE_ID = CLASS_ID::ASSEMBLY_BASE; static const uint8_t INTERFACE_ID = CLASS_ID::ASSEMBLY_BASE;
@ -16,10 +36,41 @@ public:
static const ReturnValue_t NOT_ENOUGH_CHILDREN_IN_CORRECT_STATE = static const ReturnValue_t NOT_ENOUGH_CHILDREN_IN_CORRECT_STATE =
MAKE_RETURN_CODE(0xa1); MAKE_RETURN_CODE(0xa1);
AssemblyBase(object_id_t objectId, object_id_t parentId, uint16_t commandQueueDepth = 8); AssemblyBase(object_id_t objectId, object_id_t parentId,
uint16_t commandQueueDepth = 8);
virtual ~AssemblyBase(); virtual ~AssemblyBase();
protected: protected:
// SHOULDDO: Change that OVERWRITE_HEALTH may be returned
// (or return internalState directly?)
/**
* Command children to reach [mode,submode] combination
* Can be done by setting #commandsOutstanding correctly,
* or using executeTable()
* @param mode
* @param submode
* @return
* - @c RETURN_OK if ok
* - @c NEED_SECOND_STEP if children need to be commanded again
*/
virtual ReturnValue_t commandChildren(Mode_t mode, Submode_t submode) = 0;
/**
* Check whether desired assembly mode was achieved by checking the modes
* or/and health states of child device handlers.
* The assembly template class will also call this function if a health
* or mode change of a child device handler was detected.
* @param wantedMode
* @param wantedSubmode
* @return
*/
virtual ReturnValue_t checkChildrenStateOn(Mode_t wantedMode,
Submode_t wantedSubmode) = 0;
virtual ReturnValue_t isModeCombinationValid(Mode_t mode,
Submode_t submode) = 0;
enum InternalState { enum InternalState {
STATE_NONE, STATE_NONE,
STATE_OVERWRITE_HEALTH, STATE_OVERWRITE_HEALTH,
@ -36,6 +87,7 @@ protected:
RECOVERY_WAIT RECOVERY_WAIT
} recoveryState; //!< Indicates if one of the children requested a recovery. } recoveryState; //!< Indicates if one of the children requested a recovery.
ChildrenMap::iterator recoveringDevice; ChildrenMap::iterator recoveringDevice;
/** /**
* the mode the current transition is trying to achieve. * the mode the current transition is trying to achieve.
* Can be different from the modehelper.commandedMode! * Can be different from the modehelper.commandedMode!
@ -61,8 +113,8 @@ protected:
bool handleChildrenChanged(); bool handleChildrenChanged();
/** /**
* This method is called if the children changed its mode in a way that the current * This method is called if the children changed its mode in a way that
* mode can't be kept. * the current mode can't be kept.
* Default behavior is to go to MODE_OFF. * Default behavior is to go to MODE_OFF.
* @param result The failure code which was returned by checkChildrenState. * @param result The failure code which was returned by checkChildrenState.
*/ */
@ -75,9 +127,6 @@ protected:
ReturnValue_t checkModeCommand(Mode_t mode, Submode_t submode, ReturnValue_t checkModeCommand(Mode_t mode, Submode_t submode,
uint32_t *msToReachTheMode); uint32_t *msToReachTheMode);
virtual ReturnValue_t isModeCombinationValid(Mode_t mode,
Submode_t submode) = 0;
virtual void startTransition(Mode_t mode, Submode_t submode); virtual void startTransition(Mode_t mode, Submode_t submode);
virtual void doStartTransition(Mode_t mode, Submode_t submode); virtual void doStartTransition(Mode_t mode, Submode_t submode);
@ -90,24 +139,6 @@ protected:
void sendHealthCommand(MessageQueueId_t sendTo, HealthState health); void sendHealthCommand(MessageQueueId_t sendTo, HealthState health);
//SHOULDDO: Change that OVERWRITE_HEALTH may be returned (or return internalState directly?)
/**
* command children to reach mode,submode
*
* set #commandsOutstanding correctly, or use executeTable()
*
* @param mode
* @param submode
* @return
* - @c RETURN_OK if ok
* - @c NEED_SECOND_STEP if children need to be commanded again
*/
virtual ReturnValue_t commandChildren(Mode_t mode, Submode_t submode) = 0;
//SHOULDDO: Remove wantedMode, wantedSubmode, as targetMode/submode is available?
virtual ReturnValue_t checkChildrenStateOn(Mode_t wantedMode,
Submode_t wantedSubmode) = 0;
virtual ReturnValue_t checkChildrenStateOff(); virtual ReturnValue_t checkChildrenStateOff();
ReturnValue_t checkChildrenState(); ReturnValue_t checkChildrenState();
@ -129,4 +160,4 @@ protected:
}; };
#endif /* ASSEMBLYBASE_H_ */ #endif /* FRAMEWORK_DEVICEHANDLERS_ASSEMBLYBASE_H_ */

View File

@ -5,9 +5,9 @@
SubsystemBase::SubsystemBase(object_id_t setObjectId, object_id_t parent, SubsystemBase::SubsystemBase(object_id_t setObjectId, object_id_t parent,
Mode_t initialMode, uint16_t commandQueueDepth) : Mode_t initialMode, uint16_t commandQueueDepth) :
SystemObject(setObjectId), mode(initialMode), submode(SUBMODE_NONE), childrenChangedMode( SystemObject(setObjectId), mode(initialMode), submode(SUBMODE_NONE),
false), commandsOutstanding(0), commandQueue(NULL), healthHelper(this, childrenChangedMode(false), commandsOutstanding(0), commandQueue(NULL),
setObjectId), modeHelper(this), parentId(parent) { healthHelper(this, setObjectId), modeHelper(this), parentId(parent) {
commandQueue = QueueFactory::instance()->createMessageQueue(commandQueueDepth, commandQueue = QueueFactory::instance()->createMessageQueue(commandQueueDepth,
MessageQueueMessage::MAX_MESSAGE_SIZE); MessageQueueMessage::MAX_MESSAGE_SIZE);
} }
@ -23,8 +23,8 @@ ReturnValue_t SubsystemBase::registerChild(object_id_t objectId) {
HasModesIF *child = objectManager->get<HasModesIF>(objectId); HasModesIF *child = objectManager->get<HasModesIF>(objectId);
//This is a rather ugly hack to have the changedHealth info for all children available. (needed for FOGs). //This is a rather ugly hack to have the changedHealth info for all children available. (needed for FOGs).
HasHealthIF* healthChild = objectManager->get<HasHealthIF>(objectId); HasHealthIF* healthChild = objectManager->get<HasHealthIF>(objectId);
if (child == NULL) { if (child == nullptr) {
if (healthChild == NULL) { if (healthChild == nullptr) {
return CHILD_DOESNT_HAVE_MODES; return CHILD_DOESNT_HAVE_MODES;
} else { } else {
info.commandQueue = healthChild->getCommandQueue(); info.commandQueue = healthChild->getCommandQueue();