QGCStateMachine.h

Go to the documentation of this file.

#pragma once
 
#include "AsyncFunctionState.h"
#include "CircuitBreakerState.h"
#include "ConditionalState.h"
#include "DelayState.h"
#include "EventQueuedState.h"
#include "FallbackChainState.h"
#include "FunctionState.h"
#include "LoopState.h"
#include "QGCAbstractTransition.h"
#include "QGCSignalTransition.h"
#include "GuardedTransition.h"
#include "InternalTransition.h"
#include "MachineEventTransition.h"
#include "NamedEventTransition.h"
#include "RetryTransition.h"
#include "TimeoutTransition.h"
#include "QGCAbstractState.h"
#include "QGCEventTransition.h"
#include "SignalDataTransition.h"
#include "QGCFinalState.h"
#include "QGCHistoryState.h"
#include "ParallelState.h"
#include "QGCStateMachineEvent.h"
#include "RequestMessageState.h"
#include "RetryState.h"
#include "RollbackState.h"
#include "SendMavlinkCommandState.h"
#include "SendMavlinkMessageState.h"
#include "SequenceState.h"
#include "ShowAppMessageState.h"
#include "SkippableAsyncState.h"
#include "SubMachineState.h"
#include "ProgressState.h"
#include "RetryableRequestMessageState.h"
#include "WaitForMavlinkMessageState.h"
#include "WaitForParamResponseState.h"
#include "WaitForSignalState.h"
#include "WaitStateBase.h"
#include "StateContext.h"
#include "ErrorRecoveryBuilder.h"
#include "ErrorHandlers.h"
 
#include <QtStateMachine/QStateMachine>
#include <QtStateMachine/QFinalState>
#include <QtStateMachine/QHistoryState>
#include <QtCore/QAbstractAnimation>
#include <QtCore/QJsonArray>
#include <QtCore/QString>
#include <QtCore/QVariant>
 
#include <functional>
 
class Vehicle;
class StateMachineLogger;
class StateMachineProfiler;
class StateHistoryRecorder;
 
class QGCStateMachine : public QStateMachine
{
    Q_OBJECT
    Q_DISABLE_COPY(QGCStateMachine)
 
    
    Q_PROPERTY(QString currentStateName READ currentStateName NOTIFY currentStateNameChanged)
 
    
    Q_PROPERTY(float progress READ progress NOTIFY progressUpdate)
 
    
    Q_PROPERTY(bool running READ isRunning NOTIFY runningChanged)
 
    
    Q_PROPERTY(QStringList stateHistory READ stateHistory NOTIFY stateHistoryChanged)
 
public:
    using EntryCallback = std::function<void()>;
    using ExitCallback = std::function<void()>;
    using EventHandler = std::function<bool(QEvent*)>;
 
    QGCStateMachine(const QString& machineName, Vehicle* vehicle, QObject* parent = nullptr);
 
    Vehicle *vehicle() const { return _vehicle; }
    QString machineName() const { return objectName(); }
 
    StateContext& context() { return _context; }
    const StateContext& context() const { return _context; }
 
    bool active() const { return isRunning(); }
 
    QString currentStateName() const;
 
    QStringList stateHistory() const { return _stateHistory; }
 
    void setStateHistoryLimit(int limit) { _stateHistoryLimit = limit; }
 
    // -------------------------------------------------------------------------
    // Entry/Exit Callbacks
    // -------------------------------------------------------------------------
 
    void setOnEntry(EntryCallback callback) { _entryCallback = std::move(callback); }
 
    void setOnExit(ExitCallback callback) { _exitCallback = std::move(callback); }
 
    void setCallbacks(EntryCallback onEntry, ExitCallback onExit = nullptr);
 
    // -------------------------------------------------------------------------
    // Event Handling
    // -------------------------------------------------------------------------
 
    void setEventHandler(EventHandler handler) { _eventHandler = std::move(handler); }
 
    void enablePropertyRestore();
 
    bool isPropertyRestoreEnabled() const;
 
    void setGlobalErrorState(QAbstractState* errorState);
 
    QAbstractState* globalErrorState() const { return _globalErrorState; }
 
    void registerState(QGCState* state);
 
    void registerState(QGCAbstractState* state);
 
    FunctionState* addFunctionState(const QString& stateName, std::function<void()> function);
 
    AsyncFunctionState* addAsyncFunctionState(const QString& stateName,
                                               AsyncFunctionState::SetupFunction setupFunction,
                                               int timeoutMsecs = 0);
 
    QGCState* addErrorRecoveryState(const QString& stateName,
                                    ErrorRecoveryBuilder::Action action,
                                    int maxRetries = 0,
                                    int retryDelayMsecs = 1000,
                                    ErrorRecoveryBuilder::ExhaustedBehavior exhaustedBehavior = ErrorRecoveryBuilder::EmitError,
                                    ErrorRecoveryBuilder::Action fallback = nullptr,
                                    ErrorRecoveryBuilder::VoidAction rollback = nullptr,
                                    int timeoutMsecs = 0);
 
    DelayState* addDelayState(int delayMsecs);
 
    ParallelState* addParallelState(const QString& stateName);
 
    void postEvent(const QString& eventName, const QVariant& data = QVariant(),
                   EventPriority priority = NormalPriority);
 
    int postDelayedEvent(const QString& eventName, int delayMsecs, const QVariant& data = QVariant());
 
    bool cancelDelayedEvent(int eventId);
 
    // -------------------------------------------------------------------------
    // State Configuration
    // -------------------------------------------------------------------------
 
    void setInitialState(QAbstractState* state, bool autoStart = false);
 
    QGCFinalState* addFinalState(const QString& stateName = QString());
 
    ConditionalState* addConditionalState(const QString& stateName,
                                          ConditionalState::Predicate predicate,
                                          ConditionalState::Action action = nullptr);
 
    template<typename Func>
    WaitForSignalState* addWaitForSignalState(const QString& stateName,
                                               const QObject* sender,
                                               Func signal,
                                               int timeoutMsecs = 0)
    {
        auto* state = new WaitForSignalState(stateName, this, sender, signal, timeoutMsecs);
        registerState(state);
        return state;
    }
 
    SubMachineState* addSubMachineState(const QString& stateName, SubMachineState::MachineFactory factory);
 
    EventQueuedState* addEventQueuedState(const QString& stateName,
                                          const QString& eventName,
                                          int timeoutMsecs = 0);
 
    QState* createTimedActionState(const QString& stateName,
                                   int durationMsecs,
                                   std::function<void()> onEntry = nullptr,
                                   std::function<void()> onExit = nullptr);
 
    // -------------------------------------------------------------------------
    // State Queries
    // -------------------------------------------------------------------------
 
    bool isStateActive(QAbstractState* state) const;
 
    QSet<QAbstractState*> activeStates() const { return configuration(); }
 
    QAbstractState* findState(const QString& stateName) const;
 
    template<typename T>
    QList<T*> findStates() const
    {
        return findChildren<T*>();
    }
 
    // -------------------------------------------------------------------------
    // Error Handling & Recovery
    // -------------------------------------------------------------------------
 
    bool isInErrorState() const;
 
    FunctionState* addLogAndContinueErrorState(const QString& stateName,
                                               QAbstractState* nextState,
                                               const QString& message = QString());
 
    FunctionState* addLogAndStopErrorState(const QString& stateName,
                                           const QString& message = QString());
 
    QString lastError() const { return errorString(); }
 
    void clearError(bool restart = false);
 
    bool resetToState(QAbstractState* state);
 
    bool recoverFromError();
 
    void setRecoveryState(QAbstractState* state) { _recoveryState = state; }
 
    QAbstractState* recoveryState() const { return _recoveryState; }
 
    bool attemptRecovery();
 
    // -------------------------------------------------------------------------
    // Lifecycle Helpers
    // -------------------------------------------------------------------------
 
    void ensureRunning();
 
    void stopMachine(bool deleteOnStop = true);
 
    void restart();
 
    // -------------------------------------------------------------------------
    // Transition Helpers
    // -------------------------------------------------------------------------
 
    template<typename Func>
    QSignalTransition* addTransition(QState* from, Func signal, QAbstractState* to,
                                      QAbstractAnimation* animation = nullptr)
    {
        auto* transition = from->addTransition(from, signal, to);
        if (animation) {
            transition->addAnimation(animation);
        }
        return transition;
    }
 
    template<typename Func>
    GuardedTransition* addGuardedTransition(QState* from, Func signal, QAbstractState* to,
                                            GuardedTransition::Guard guard,
                                            QAbstractAnimation* animation = nullptr)
    {
        auto* transition = new GuardedTransition(from, signal, to, std::move(guard));
        from->addTransition(transition);
        if (animation) {
            transition->addAnimation(animation);
        }
        return transition;
    }
 
    MachineEventTransition* addEventTransition(QState* from, const QString& eventName, QAbstractState* to,
                                               QAbstractAnimation* animation = nullptr);
 
    TimeoutTransition* addTimeoutTransition(QState* from, int timeoutMsecs, QAbstractState* to,
                                            QAbstractAnimation* animation = nullptr);
 
    template<typename SenderType, typename Func>
    RetryTransition* addRetryTransition(SenderType* from, Func signal,
                                        QAbstractState* to,
                                        std::function<void()> retryAction,
                                        int maxRetries = 1)
    {
        auto* transition = new RetryTransition(from, signal, to, std::move(retryAction), maxRetries);
        from->addTransition(transition);
        return transition;
    }
 
    template<typename SenderType, typename Func>
    GuardedTransition* addConditionalTransition(SenderType* from, Func signal,
                                                 QAbstractState* to,
                                                 std::function<bool()> guard)
    {
        auto* transition = new GuardedTransition(from, signal, to, std::move(guard));
        from->addTransition(transition);
        return transition;
    }
 
    template<typename Sender, typename Signal>
    QSignalTransition* addSelfLoopTransition(QState* state,
                                              Sender* sender,
                                              Signal signal,
                                              std::function<void()> action)
    {
        auto* transition = state->addTransition(sender, signal, state);
        if (action) {
            connect(transition, &QAbstractTransition::triggered, this, std::move(action));
        }
        return transition;
    }
 
    template<typename Sender, typename Signal>
    InternalTransition* addInternalTransition(QState* state,
                                               Sender* sender,
                                               Signal signal,
                                               std::function<void()> action)
    {
        auto* transition = new InternalTransition(sender, signal, std::move(action));
        state->addTransition(transition);
        return transition;
    }
 
    // -------------------------------------------------------------------------
    // State Introspection
    // -------------------------------------------------------------------------
 
    QList<QAbstractTransition*> transitionsFrom(QAbstractState* state) const;
 
    QList<QAbstractTransition*> transitionsTo(QAbstractState* state) const;
 
    QList<QAbstractState*> reachableFrom(QAbstractState* state) const;
 
    QList<QAbstractState*> predecessorsOf(QAbstractState* state) const;
 
    // -------------------------------------------------------------------------
    // Debugging & Visualization
    // -------------------------------------------------------------------------
 
    QString dumpCurrentState() const;
 
    QString dumpConfiguration() const;
 
    void logCurrentState() const;
 
    void logConfiguration() const;
 
    void setHistoryRecordingEnabled(bool enabled, int maxEntries = 1000);
    bool historyRecordingEnabled() const;
    QString dumpRecordedHistory() const;
    QJsonArray recordedHistoryJson() const;
 
    void setProfilingEnabled(bool enabled);
    bool profilingEnabled() const;
    QString profilingSummary() const;
 
    void setStructuredLoggingEnabled(bool enabled);
    bool structuredLoggingEnabled() const;
 
    QString exportAsDot() const;
 
    QList<QAbstractState*> unreachableStates() const;
 
    int maxPathLength() const;
 
    QList<QAbstractState*> deadEndStates() const;
 
    // -------------------------------------------------------------------------
    // Progress Tracking
    // -------------------------------------------------------------------------
 
    void setProgressWeights(const QList<QPair<QAbstractState*, int>>& stateWeights);
 
    void setSubProgress(float subProgress);
 
    float progress() const;
 
    void resetProgress();
 
    // -------------------------------------------------------------------------
    // Timeout Configuration
    // -------------------------------------------------------------------------
 
    void setTimeoutOverride(const QString& stateName, int timeoutMsecs);
 
    void removeTimeoutOverride(const QString& stateName);
 
    int timeoutOverride(const QString& stateName) const;
 
    QHash<QString, int> allTimeoutOverrides() const { return _timeoutOverrides; }
 
    void clearTimeoutOverrides() { _timeoutOverrides.clear(); }
 
    QHash<QString, int> timeoutStats() const { return _timeoutStats; }
 
    void recordTimeout(const QString& stateName);
 
    void clearTimeoutStats() { _timeoutStats.clear(); }
 
public slots:
    void start();
 
signals:
    void error();
 
    void progressUpdate(float progress);
 
    void machineEvent(const QString& eventName);
 
    void currentStateNameChanged();
 
    void runningChanged();
 
    void stateHistoryChanged();
 
protected:
    virtual void onEnter() {}
 
    virtual void onLeave() {}
 
    // QStateMachine overrides
    void onEntry(QEvent* event) override;
    void onExit(QEvent* event) override;
    bool event(QEvent* event) override;
 
private:
    void _onStateEntered();
    float _calculateProgress() const;
 
    Vehicle* _vehicle = nullptr;
    QAbstractState* _globalErrorState = nullptr;
    QAbstractState* _recoveryState = nullptr;
    bool _deleteOnStop = false;
    EntryCallback _entryCallback;
    ExitCallback _exitCallback;
    EventHandler _eventHandler;
 
    // Progress tracking
    QList<QAbstractState*> _progressStates;
    QList<int> _progressWeights;
    int _progressTotalWeight = 0;
    int _progressCurrentIndex = -1;
    float _progressSubProgress = 0.0f;
    float _progressLastEmitted = 0.0f;
 
    // Inter-state data context
    StateContext _context;
 
    // QML state history
    QStringList _stateHistory;
    int _stateHistoryLimit = 20;
 
    // Timeout configuration
    QHash<QString, int> _timeoutOverrides;
    QHash<QString, int> _timeoutStats;
 
    // Optional runtime diagnostics helpers (lazy-created)
    StateHistoryRecorder* _historyRecorder = nullptr;
    StateMachineProfiler* _profiler = nullptr;
    StateMachineLogger* _logger = nullptr;
};