merged AI doc, some new pages
This commit is contained in:
@@ -1,13 +1,12 @@
|
||||
/*! \file pistatemachine_state.h
|
||||
* \ingroup StateMachine
|
||||
* \~\brief
|
||||
* \~english State machine node
|
||||
* \~russian Узел машины состояний
|
||||
*/
|
||||
//! \~\file pistatemachine_state.h
|
||||
//! \~\ingroup StateMachine
|
||||
//! \~\brief
|
||||
//! \~english Declares states used by PIStateMachine
|
||||
//! \~russian Объявляет состояния, используемые в PIStateMachine
|
||||
/*
|
||||
PIP - Platform Independent Primitives
|
||||
State machine node
|
||||
Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
|
||||
Ivan Pelipenko peri4ko@yandex.ru
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Lesser General Public License as published by
|
||||
@@ -31,52 +30,141 @@
|
||||
#include "pisystemtime.h"
|
||||
|
||||
|
||||
//! \ingroup StateMachine
|
||||
//! \~\ingroup StateMachine
|
||||
//! \~\brief
|
||||
//! \~english Base class for states in a hierarchical state machine.
|
||||
//! \~russian Базовый класс состояния в иерархической машине состояний.
|
||||
//! \~\details
|
||||
//! \~english
|
||||
//! A state can own child states and outgoing transitions. Compound states activate
|
||||
//! either their initial child state or all children when parallel mode is enabled.
|
||||
//! \~russian
|
||||
//! Состояние может владеть дочерними состояниями и исходящими переходами.
|
||||
//! Составные состояния активируют либо начальное дочернее состояние, либо все
|
||||
//! дочерние состояния при включенном параллельном режиме.
|
||||
class PIP_EXPORT PIStateBase {
|
||||
friend class PIStateMachine;
|
||||
friend class PITransitionBase;
|
||||
friend class PIStateFinal;
|
||||
|
||||
|
||||
public:
|
||||
//! \~english Creates a state with an optional diagnostic name.
|
||||
//! \~russian Создает состояние с необязательным именем для диагностики.
|
||||
PIStateBase(const PIString & n = {}): name_(n) { ; }
|
||||
|
||||
//! \~english Destroys the state together with owned child states and transitions.
|
||||
//! \~russian Уничтожает состояние вместе с принадлежащими дочерними состояниями и переходами.
|
||||
virtual ~PIStateBase();
|
||||
|
||||
|
||||
//! \~english Called when the state becomes active.
|
||||
//! \~russian Вызывается при активации состояния.
|
||||
virtual void onEnter() {}
|
||||
|
||||
//! \~english Called when the state becomes inactive.
|
||||
//! \~russian Вызывается при деактивации состояния.
|
||||
virtual void onExit() {}
|
||||
|
||||
//! \~english Called when a final child finishes this state.
|
||||
//! \~russian Вызывается, когда финальное дочернее состояние завершает это состояние.
|
||||
virtual void onFinish() {}
|
||||
|
||||
|
||||
//! \~english Returns the root state machine.
|
||||
//! \~russian Возвращает корневую машину состояний.
|
||||
PIStateMachine * machine() const { return root; }
|
||||
|
||||
//! \~english Returns the parent state.
|
||||
//! \~russian Возвращает родительское состояние.
|
||||
PIStateBase * parent() const { return parent_state; }
|
||||
|
||||
//! \~english Returns the active child of a non-parallel compound state.
|
||||
//! \~russian Возвращает активное дочернее состояние непараллельного составного состояния.
|
||||
PIStateBase * activeChild() const { return active_state; }
|
||||
|
||||
//! \~english Returns active child states.
|
||||
//! \~russian Возвращает активные дочерние состояния.
|
||||
PIVector<PIStateBase *> activeChildren() const;
|
||||
|
||||
//! \~english Returns active atomic leaf states below this state.
|
||||
//! \~russian Возвращает активные атомарные листовые состояния под этим состоянием.
|
||||
PIVector<PIStateBase *> activeAtomics() const;
|
||||
|
||||
|
||||
//! \~english Adds a child state owned by this state.
|
||||
//! \~russian Добавляет дочернее состояние, которым владеет это состояние.
|
||||
void addState(PIStateBase * s);
|
||||
|
||||
//! \~english Adds multiple child states owned by this state.
|
||||
//! \~russian Добавляет несколько дочерних состояний, которыми владеет это состояние.
|
||||
void addStates(PIVector<PIStateBase *> s);
|
||||
|
||||
//! \~english Sets the initial child state for a non-parallel compound state.
|
||||
//! \~russian Задает начальное дочернее состояние для непараллельного составного состояния.
|
||||
void setInitialState(PIStateBase * s);
|
||||
|
||||
|
||||
//! \~english Adds an event-driven transition from this state to \a target.
|
||||
//! \~russian Добавляет переход по событию из этого состояния в \a target.
|
||||
PITransitionBase * addTransition(PIStateBase * target, int event_id);
|
||||
|
||||
//! \~english Adds a timeout transition that fires while this state stays active.
|
||||
//! \~russian Добавляет переход по таймауту, который срабатывает пока это состояние активно.
|
||||
PITransitionTimeout * addTimeoutTransition(PIStateBase * target, PISystemTime timeout);
|
||||
|
||||
|
||||
//! \~english Enables or disables parallel activation of child states.
|
||||
//! \~russian Включает или выключает параллельную активацию дочерних состояний.
|
||||
void setParallel(bool yes) { is_parallel = yes; }
|
||||
|
||||
|
||||
//! \~english Returns the state name.
|
||||
//! \~russian Возвращает имя состояния.
|
||||
const PIString & getName() const { return name_; }
|
||||
|
||||
//! \~english Returns true for the root machine object.
|
||||
//! \~russian Возвращает true для корневого объекта машины состояний.
|
||||
bool isStateMachine() const { return is_root; }
|
||||
|
||||
//! \~english Returns true if the state is currently active.
|
||||
//! \~russian Возвращает true, если состояние сейчас активно.
|
||||
bool isActive() const { return is_active; }
|
||||
|
||||
//! \~english Returns true if child states are activated in parallel.
|
||||
//! \~russian Возвращает true, если дочерние состояния активируются параллельно.
|
||||
bool isParallel() const { return is_parallel; }
|
||||
|
||||
//! \~english Returns true if the state is marked as final.
|
||||
//! \~russian Возвращает true, если состояние помечено как финальное.
|
||||
bool isFinal() const { return is_final; }
|
||||
|
||||
//! \~english Returns true if the state has no children.
|
||||
//! \~russian Возвращает true, если у состояния нет дочерних состояний.
|
||||
bool isAtomic() const { return children.isEmpty(); }
|
||||
|
||||
//! \~english Returns true if the state owns child states.
|
||||
//! \~russian Возвращает true, если состояние содержит дочерние состояния.
|
||||
bool isCompound() const { return children.isNotEmpty(); }
|
||||
|
||||
//! \~english Returns direct child states.
|
||||
//! \~russian Возвращает прямые дочерние состояния.
|
||||
const PIVector<PIStateBase *> & getChildren() const { return children; }
|
||||
|
||||
//! \~english Returns outgoing transitions owned by this state.
|
||||
//! \~russian Возвращает исходящие переходы, принадлежащие этому состоянию.
|
||||
const PIVector<PITransitionBase *> & getTransitions() const { return transitions; }
|
||||
|
||||
|
||||
//! \~english Prints the state tree and active branches to piCout.
|
||||
//! \~russian Печатает дерево состояний и активные ветви в piCout.
|
||||
void print(PIString prefix = {});
|
||||
|
||||
//! \~english Returns this state and all descendant states.
|
||||
//! \~russian Возвращает это состояние и все дочерние состояния.
|
||||
PIVector<PIStateBase *> gatherStates();
|
||||
|
||||
|
||||
private:
|
||||
bool start(bool force = false);
|
||||
void setActive(bool yes);
|
||||
@@ -100,39 +188,67 @@ private:
|
||||
};
|
||||
|
||||
|
||||
//! \~\ingroup StateMachine
|
||||
//! \~\brief
|
||||
//! \~english State implementation that forwards enter and exit virtual methods to callbacks.
|
||||
//! \~russian Реализация состояния, которая перенаправляет виртуальные методы входа и выхода в callback-функции.
|
||||
class PIP_EXPORT PIStateLambda: public PIStateBase {
|
||||
public:
|
||||
//! \~english Creates a state backed by enter and exit callbacks.
|
||||
//! \~russian Создает состояние с callback-функциями входа и выхода.
|
||||
PIStateLambda(std::function<void()> on_enter, std::function<void()> on_exit = nullptr, const PIString & n = {}): PIStateBase(n) {
|
||||
enter = on_enter;
|
||||
exit = on_exit;
|
||||
}
|
||||
|
||||
|
||||
//! \~english Executes the enter callback.
|
||||
//! \~russian Выполняет callback-функцию входа.
|
||||
void onEnter() override {
|
||||
if (enter) enter();
|
||||
}
|
||||
|
||||
//! \~english Executes the exit callback.
|
||||
//! \~russian Выполняет callback-функцию выхода.
|
||||
void onExit() override {
|
||||
if (exit) exit();
|
||||
}
|
||||
|
||||
|
||||
private:
|
||||
std::function<void()> enter, exit;
|
||||
};
|
||||
|
||||
|
||||
//! \~\ingroup StateMachine
|
||||
//! \~\brief
|
||||
//! \~english Final state that finishes its parent state when entered.
|
||||
//! \~russian Финальное состояние, которое завершает родительское состояние при входе.
|
||||
class PIP_EXPORT PIStateFinal: public PIStateBase {
|
||||
public:
|
||||
//! \~english Creates a final state with an optional callback executed on entry.
|
||||
//! \~russian Создает финальное состояние с необязательной callback-функцией, выполняемой при входе.
|
||||
PIStateFinal(std::function<void()> on_finish = nullptr, const PIString & n = {}): PIStateBase(n) {
|
||||
is_final = true;
|
||||
enter = on_finish;
|
||||
}
|
||||
|
||||
|
||||
//! \~english Executes the finish callback when the final state is entered.
|
||||
//! \~russian Выполняет callback завершения при входе в финальное состояние.
|
||||
void onEnter() override {
|
||||
if (enter) enter();
|
||||
}
|
||||
|
||||
|
||||
private:
|
||||
std::function<void()> enter;
|
||||
};
|
||||
|
||||
|
||||
//! \relatesalso PIStateBase
|
||||
//! \~english Writes a textual representation of a state to PICout.
|
||||
//! \~russian Записывает текстовое представление состояния в PICout.
|
||||
inline PICout operator<<(PICout c, PIStateBase * s) {
|
||||
if (!s)
|
||||
c << "state(nullptr)";
|
||||
|
||||
Reference in New Issue
Block a user