pip/doc/pages/state_machine.md

~english \page state_machine State machine ~russian \page state_machine Машина состояний

~english

State Machine

State Machine Description

State machine is a behavioral design pattern that allows an object to change its behavior when its internal state changes. Implementation in PIP is based on the SCXML (State Chart XML) standard.

SCXML Concepts

• State — a node in the state tree, can be atomic or compound
• Transition — a connection between states that triggers on an event
• Event — a trigger that causes a transition
• Guard — a condition that must be true for a transition to execute
• Action — an operation executed during a transition
• Parallel — a state where all substates are activated simultaneously

PIP State Machine Features

• Cannot create state, event, transition on stack — all objects are created via new and managed via pointers
• State machine is the root state — PIStateMachine inherits from PIStateBase
• All transitions and states are automatically deleted — when the parent object is destroyed

State Types

• Atomic state — a state without nested substates
• Compound state — a state containing nested substates
• Final state — a terminating state indicating the end of machine execution
• Parallel state — a state where all substates are activated simultaneously

Transition Types

• Normal transition — triggers on receiving a specific event
• Timeout transition — triggers automatically after a specified time interval
• Guarded transition — triggers only when a specific condition is met

State Machine API

Main Classes

PIStateMachine

Main state machine class.

Key methods:

• bool start() — starts state machine execution
• bool isRunning() — checks if state machine is running
• void setOnFinish(std::function<void()> f) — sets finish callback
• bool postEvent(int event_id, Args... args) — posts event to state machine

PIStateBase

Base class for all states.

Key methods:

• virtual void onEnter() — called when state is entered
• virtual void onExit() — called when state is exited
• void addState(PIStateBase *s) — adds child state
• PITransitionBase *addTransition(PIStateBase *target, int event_id) — adds transition
• PITransitionTimeout *addTimeoutTransition(PIStateBase *target, PISystemTime timeout) — adds timeout transition
• void setParallel(bool yes) — sets parallel mode

PIStateLambda

State with lambda callbacks.

\code{.cpp} PIStateLambda(std::function<void()> on_enter, std::function<void()> on_exit = nullptr, const PIString &n = {}) \endcode

PIStateFinal

Final state of state machine.

\code{.cpp} PIStateFinal(std::function<void()> on_finish = nullptr, const PIString &n = {}) \endcode

PITransitionBase

Base class for transitions.

Key methods:

• PITransitionBase *addGuard(std::function<R(Args...)> f) — adds guard function
• PITransitionBase *addAction(std::function<void()> a) — adds action
• void trigger() — triggers transition

PITransitionTimeout

Transition that triggers after a specified timeout.

Usage Examples

Simple State Machine

\code{.cpp} #include "pistatemachine.h" #include "pisystemtime.h"

// Create state machine PIStateMachine *machine = new PIStateMachine("Main");

// Create states PIStateLambda *idle = new PIStateLambda( { piCout << "Entering Idle state\n"; }, { piCout << "Exiting Idle state\n"; }, "Idle" ); PIStateLambda *running = new PIStateLambda( { piCout << "Entering Running state\n"; }, { piCout << "Exiting Running state\n"; }, "Running" ); PIStateFinal *finish = new PIStateFinal( { piCout << "Machine finished\n"; }, "Finish" );

// Add states machine->addState(idle); machine->addState(running); machine->addState(finish);

// Set initial state idle->setInitialState(idle); running->setInitialState(running); machine->setInitialState(idle);

// Add transitions idle->addTransition(running, 1); running->addTransition(finish, 2);

// Set finish callback machine->setOnFinish( { piCout << "Machine execution completed\n"; });

// Start machine machine->start();

// Post events machine->postEvent(1); // Transition to Running machine->postEvent(2); // Transition to Finish \endcode

Guarded Transitions

\code{.cpp} PIStateMachine *machine = new PIStateMachine("With Guards");

PIStateLambda *stateA = new PIStateLambda( { piCout << "State A\n"; }, nullptr, "A"); PIStateLambda *stateB = new PIStateLambda( { piCout << "State B\n"; }, nullptr, "B"); PIStateLambda *stateC = new PIStateLambda( { piCout << "State C\n"; }, nullptr, "C");

machine->addState(stateA); machine->addState(stateB); machine->addState(stateC);

stateA->setInitialState(stateA); machine->setInitialState(stateA);

// Transition with guard function auto *t1 = stateA->addTransition(stateB, 1); t1->addGuard([](int value) -> bool { return value > 10; });

// Transition with another guard function auto *t2 = stateB->addTransition(stateC, 2); t2->addGuard([](const PIString &msg) -> bool { return msg == "allowed"; });

machine->start();

// First call will not execute (value <= 10) machine->postEvent(1, 5);

// Second call will execute (value > 10) machine->postEvent(1, 15);

// First call will not execute (msg != "allowed") machine->postEvent(2, "test");

// Second call will execute (msg == "allowed") machine->postEvent(2, "allowed"); \endcode

Timeout Transitions

\code{.cpp} PIStateMachine *machine = new PIStateMachine("With Timeout");

PIStateLambda *working = new PIStateLambda( { piCout << "Working...\n"; }, { piCout << "Stop working\n"; }, "Working" ); PIStateLambda *timeoutState = new PIStateLambda( { piCout << "Timeout occurred\n"; }, nullptr, "Timeout"); PIStateFinal *finish = new PIStateFinal( { piCout << "Done\n"; }, "Finish");

machine->addState(working); machine->addState(timeoutState); machine->addState(finish);

working->setInitialState(working); machine->setInitialState(working);

// Add timeout transition (after 5 seconds) working->addTimeoutTransition(timeoutState, PISystemTime::fromSeconds(5));

// Add transition from timeoutState to finish timeoutState->addTransition(finish, 1);

machine->start(); \endcode

Compound States

\code{.cpp} PIStateMachine *machine = new PIStateMachine("Compound States");

// Root state (machine) PIStateLambda *root = new PIStateLambda( { piCout << "Root state\n"; }, nullptr, "Root");

// Compound state with substates PIStateLambda *parent = new PIStateLambda( { piCout << "Parent state\n"; }, nullptr, "Parent"); PIStateLambda *child1 = new PIStateLambda( { piCout << "Child 1\n"; }, nullptr, "Child1"); PIStateLambda *child2 = new PIStateLambda( { piCout << "Child 2\n"; }, nullptr, "Child2");

parent->setInitialState(child1); parent->addState(child1); parent->addState(child2); root->addState(parent);

machine->addState(root); machine->setInitialState(root);

// Add transitions root->addTransition(parent, 1); parent->addTransition(root, 2);

machine->start();

// Transition to parent machine->postEvent(1);

// Transition back machine->postEvent(2); \endcode

Parallel States

\code{.cpp} PIStateMachine *machine = new PIStateMachine("Parallel States");

PIStateLambda *root = new PIStateLambda( { piCout << "Root\n"; }, nullptr, "Root"); PIStateLambda *parallel = new PIStateLambda( { piCout << "Parallel\n"; }, nullptr, "Parallel"); PIStateLambda *sub1 = new PIStateLambda( { piCout << "Substate 1\n"; }, nullptr, "Sub1"); PIStateLambda *sub2 = new PIStateLambda( { piCout << "Substate 2\n"; }, nullptr, "Sub2");

// Enable parallel mode parallel->setParallel(true); parallel->addState(sub1); parallel->addState(sub2); parallel->setInitialState(sub1); root->addState(parallel);

machine->addState(root); machine->setInitialState(root);

machine->start();

// When entering parallel, both substates are activated simultaneously \endcode

Transitions with Actions

\code{.cpp} PIStateMachine *machine = new PIStateMachine("With Actions");

PIStateLambda *stateA = new PIStateLambda( { piCout << "State A\n"; }, nullptr, "A"); PIStateLambda *stateB = new PIStateLambda( { piCout << "State B\n"; }, nullptr, "B");

machine->addState(stateA); machine->addState(stateB);

machine->setInitialState(stateA);

// Add transition with action auto *t = stateA->addTransition(stateB, 1); t->addAction( { piCout << "Action during transition\n"; });

machine->start(); machine->postEvent(1); \endcode

Thread Safety

State machine is thread-safe. The postEvent method uses a queue to handle nested calls, allowing safe event posting from different threads.

Usage Rules

Cannot Create on Stack

\code{.cpp} // ❌ WRONG PIStateLambda state( {}, nullptr, "State");

// ✅ CORRECT PIStateLambda *state = new PIStateLambda( {}, nullptr, "State"); \endcode

Proper Object Hierarchy

\code{.cpp} PIStateMachine *machine = new PIStateMachine("Main");

// States are created via new and added to machine or another state PIStateLambda *state1 = new PIStateLambda( {}, nullptr, "State1"); PIStateLambda *state2 = new PIStateLambda( {}, nullptr, "State2");

machine->addState(state1); machine->addState(state2);

// Transitions are added to states via addTransition state1->addTransition(state2, 1);

// Machine is started machine->start(); \endcode

Memory Cleanup

All objects (states, transitions) are automatically deleted when the parent object is destroyed:

• When PIStateMachine is destroyed, all states and transitions are deleted
• When PIStateBase is destroyed, all child states and transitions are deleted

Debugging

For debugging, you can use the print() method to output the state tree:

\code{.cpp} machine->print(); \endcode

Also, you can use activeAtomics() to get a list of active states.

Related Modules

• \ref DateTime module for PISystemTime used in timeout transitions

~russian

Машина состояний

Описание машины состояний

Машина состояний — это поведенческий паттерн проектирования, который позволяет объекту изменять свое поведение при изменении внутреннего состояния. Реализация в PIP основана на стандарте SCXML (State Chart XML).

Основные концепции SCXML

• State (Состояние) — узел в дереве состояний, может быть атомарным или составным
• Transition (Переход) — связь между состояниями, срабатывает при событии
• Event (Событие) — триггер, вызывающий переход
• Guard (Сторожевая функция) — условие, которое должно быть истинным для выполнения перехода
• Action (Действие) — операция, выполняемая при переходе
• Parallel (Параллельное состояние) — состояние, в котором все подсостояния активируются одновременно

Особенности реализации PIP

• Нельзя создавать state, event, transition в стеке — все объекты создаются через new и управляются через указатели
• Машина состояний — это корневой state — PIStateMachine наследуется от PIStateBase
• Все переходы и состояния удаляются автоматически — при уничтожении родительского объекта

Основные типы состояний

• Атомарное состояние — состояние без вложенных подсостояний
• Составное состояние — состояние, содержащее вложенные подсостояния
• Финальное состояние — завершающее состояние, указывающее на окончание работы машины
• Параллельное состояние — состояние, в котором все подсостояния активируются одновременно

Виды переходов

• Обычный переход — срабатывает при получении определенного события
• Переход по таймауту — срабатывает автоматически через заданный промежуток времени
• Переход с guard — срабатывает только при выполнении определенного условия

PIP State Machine API

Основные классы

PIStateMachine

Основной класс машины состояний.

Ключевые методы:

• bool start() — запускает выполнение машины состояний
• bool isRunning() — проверяет, запущена ли машина
• void setOnFinish(std::function<void()> f) — устанавливает коллбэк завершения
• bool postEvent(int event_id, Args... args) — отправляет событие в машину состояний

PIStateBase

Базовый класс для всех состояний.

Ключевые методы:

• virtual void onEnter() — вызывается при входе в состояние
• virtual void onExit() — вызывается при выходе из состояния
• void addState(PIStateBase *s) — добавляет дочернее состояние
• PITransitionBase *addTransition(PIStateBase *target, int event_id) — добавляет переход
• PITransitionTimeout *addTimeoutTransition(PIStateBase *target, PISystemTime timeout) — добавляет переход по таймауту
• void setParallel(bool yes) — устанавливает параллельный режим

PIStateLambda

Состояние с lambda-коллбэками.

\code{.cpp} PIStateLambda(std::function<void()> on_enter, std::function<void()> on_exit = nullptr, const PIString &n = {}) \endcode

PIStateFinal

Финальное состояние машины состояний.

\code{.cpp} PIStateFinal(std::function<void()> on_finish = nullptr, const PIString &n = {}) \endcode

PITransitionBase

Базовый класс для переходов.

Ключевые методы:

• PITransitionBase *addGuard(std::function<R(Args...)> f) — добавляет сторожевую функцию
• PITransitionBase *addAction(std::function<void()> a) — добавляет действие
• void trigger() — запускает переход

PITransitionTimeout

Переход, срабатывающий через заданный промежуток времени.

Примеры использования

Простая машина состояний

\code{.cpp} #include "pistatemachine.h" #include "pisystemtime.h"

// Создаем машину состояний PIStateMachine *machine = new PIStateMachine("Main");

// Создаем состояния PIStateLambda *idle = new PIStateLambda( { piCout << "Entering Idle state\n"; }, { piCout << "Exiting Idle state\n"; }, "Idle" ); PIStateLambda *running = new PIStateLambda( { piCout << "Entering Running state\n"; }, { piCout << "Exiting Running state\n"; }, "Running" ); PIStateFinal *finish = new PIStateFinal( { piCout << "Machine finished\n"; }, "Finish" );

// Добавляем состояния machine->addState(idle); machine->addState(running); machine->addState(finish);

// Устанавливаем начальное состояние idle->setInitialState(idle); running->setInitialState(running); machine->setInitialState(idle);

// Добавляем переходы idle->addTransition(running, 1); running->addTransition(finish, 2);

// Устанавливаем коллбэк завершения machine->setOnFinish( { piCout << "Machine execution completed\n"; });

// Запускаем машину machine->start();

// Отправляем события machine->postEvent(1); // Перейти в Running machine->postEvent(2); // Перейти в Finish \endcode

Машина состояний с guard-функциями

\code{.cpp} PIStateMachine *machine = new PIStateMachine("With Guards");

PIStateLambda *stateA = new PIStateLambda( { piCout << "State A\n"; }, nullptr, "A"); PIStateLambda *stateB = new PIStateLambda( { piCout << "State B\n"; }, nullptr, "B"); PIStateLambda *stateC = new PIStateLambda( { piCout << "State C\n"; }, nullptr, "C");

machine->addState(stateA); machine->addState(stateB); machine->addState(stateC);

stateA->setInitialState(stateA); machine->setInitialState(stateA);

// Переход с guard-функцией auto *t1 = stateA->addTransition(stateB, 1); t1->addGuard([](int value) -> bool { return value > 10; });

// Переход с другой guard-функцией auto *t2 = stateB->addTransition(stateC, 2); t2->addGuard([](const PIString &msg) -> bool { return msg == "allowed"; });

machine->start();

// Первый вызов не выполнится (value <= 10) machine->postEvent(1, 5);

// Второй вызов выполнится (value > 10) machine->postEvent(1, 15);

// Первый вызов не выполнится (msg != "allowed") machine->postEvent(2, "test");

// Второй вызов выполнится (msg == "allowed") machine->postEvent(2, "allowed"); \endcode

Машина состояний с таймаутами

\code{.cpp} PIStateMachine *machine = new PIStateMachine("With Timeout");

PIStateLambda *working = new PIStateLambda( { piCout << "Working...\n"; }, { piCout << "Stop working\n"; }, "Working" ); PIStateLambda *timeoutState = new PIStateLambda( { piCout << "Timeout occurred\n"; }, nullptr, "Timeout"); PIStateFinal *finish = new PIStateFinal( { piCout << "Done\n"; }, "Finish");

machine->addState(working); machine->addState(timeoutState); machine->addState(finish);

working->setInitialState(working); machine->setInitialState(working);

// Добавляем переход по таймауту (через 5 секунд) working->addTimeoutTransition(timeoutState, PISystemTime::fromSeconds(5));

// Добавляем переход из timeoutState в finish timeoutState->addTransition(finish, 1);

machine->start(); \endcode

Составные состояния

\code{.cpp} PIStateMachine *machine = new PIStateMachine("Compound States");

// Корневое состояние (машина) PIStateLambda *root = new PIStateLambda( { piCout << "Root state\n"; }, nullptr, "Root");

// Составное состояние с подсостояниями PIStateLambda *parent = new PIStateLambda( { piCout << "Parent state\n"; }, nullptr, "Parent"); PIStateLambda *child1 = new PIStateLambda( { piCout << "Child 1\n"; }, nullptr, "Child1"); PIStateLambda *child2 = new PIStateLambda( { piCout << "Child 2\n"; }, nullptr, "Child2");

parent->setInitialState(child1); parent->addState(child1); parent->addState(child2); root->addState(parent);

machine->addState(root); machine->setInitialState(root);

// Добавляем переходы root->addTransition(parent, 1); parent->addTransition(root, 2);

machine->start();

// Переход в parent machine->postEvent(1);

// Переход обратно machine->postEvent(2); \endcode

Параллельные состояния

\code{.cpp} PIStateMachine *machine = new PIStateMachine("Parallel States");

PIStateLambda *root = new PIStateLambda( { piCout << "Root\n"; }, nullptr, "Root"); PIStateLambda *parallel = new PIStateLambda( { piCout << "Parallel\n"; }, nullptr, "Parallel"); PIStateLambda *sub1 = new PIStateLambda( { piCout << "Substate 1\n"; }, nullptr, "Sub1"); PIStateLambda *sub2 = new PIStateLambda( { piCout << "Substate 2\n"; }, nullptr, "Sub2");

// Включаем параллельный режим parallel->setParallel(true); parallel->addState(sub1); parallel->addState(sub2); parallel->setInitialState(sub1); root->addState(parallel);

machine->addState(root); machine->setInitialState(root);

machine->start();

// При входе в parallel оба подсостояния активируются одновременно \endcode

Машина состояний с действиями

\code{.cpp} PIStateMachine *machine = new PIStateMachine("With Actions");

PIStateLambda *stateA = new PIStateLambda( { piCout << "State A\n"; }, nullptr, "A"); PIStateLambda *stateB = new PIStateLambda( { piCout << "State B\n"; }, nullptr, "B");

machine->addState(stateA); machine->addState(stateB);

machine->setInitialState(stateA);

// Добавляем переход с действием auto *t = stateA->addTransition(stateB, 1); t->addAction( { piCout << "Action during transition\n"; });

machine->start(); machine->postEvent(1); \endcode

Потокобезопасность

Машина состояний PIP потокобезопасна. Метод postEvent использует очередь для обработки вложенных вызовов, что позволяет безопасно отправлять события из разных потоков.

Правила использования

Нельзя создавать в стеке

\code{.cpp} // ❌ НЕЛЬЗЯ PIStateLambda state( {}, nullptr, "State");

// ✅ ПРАВИЛЬНО PIStateLambda *state = new PIStateLambda( {}, nullptr, "State"); \endcode

Правильная иерархия объектов

\code{.cpp} PIStateMachine *machine = new PIStateMachine("Main");

// Состояния создаются через new и добавляются в машину или другое состояние PIStateLambda *state1 = new PIStateLambda( {}, nullptr, "State1"); PIStateLambda *state2 = new PIStateLambda( {}, nullptr, "State2");

machine->addState(state1); machine->addState(state2);

// Переходы добавляются к состояниям через addTransition state1->addTransition(state2, 1);

// Машина запускается machine->start(); \endcode

Очистка памяти

Все объекты (состояния, переходы) автоматически удаляются при уничтожении родительского объекта:

• При уничтожении PIStateMachine удаляются все состояния и переходы
• При уничтожении PIStateBase удаляются все дочерние состояния и переходы

Отладка

Для отладки можно использовать метод print() для вывода дерева состояний:

\code{.cpp} machine->print(); \endcode

Также можно использовать activeAtomics() для получения списка активных состояний.

Связанные модули

• \ref DateTime модуль для PISystemTime, используемого в переходах по таймауту