StateOS
Loading...
Searching...
No Matches
osstatemachine.h
1/******************************************************************************
2
3 @file StateOS: osstatemachine.h
4 @author Rajmund Szymanski
5 @date 18.11.2025
6 @brief This file contains definitions for StateOS.
7
8 ******************************************************************************
9
10 Copyright (c) 2018-2022 Rajmund Szymanski. All rights reserved.
11
12 Permission is hereby granted, free of charge, to any person obtaining a copy
13 of this software and associated documentation files (the "Software"), to
14 deal in the Software without restriction, including without limitation the
15 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
16 sell copies of the Software, and to permit persons to whom the Software is
17 furnished to do so, subject to the following conditions:
18
19 The above copyright notice and this permission notice shall be included
20 in all copies or substantial portions of the Software.
21
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
23 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
28 IN THE SOFTWARE.
29
30 ******************************************************************************/
31
32#ifndef __STATEOS_HSM_H
33#define __STATEOS_HSM_H
34
35#include "oskernel.h"
36#include "osclock.h"
37#include "oseventqueue.h"
38
44
45/* -------------------------------------------------------------------------- */
46
47enum
48{
49 hsmALL = 0,// the state action applies to all events
50 hsmStop, // stop the state machine
51 hsmExit, // exit from the state during transition
52 hsmEntry, // entry to the state during transition
53 hsmInit, // init the state after transition
54 hsmUser, // values less than hsmUser are reserved for the system
55};
56
60
61typedef struct __hsm_state hsm_state_t;
62
66
67typedef struct __hsm_action hsm_action_t;
68
72
73typedef struct __hsm hsm_t;
74
78
79typedef void hsm_handler_t(hsm_t *, unsigned);
80
84
85struct __hsm_state
86{
87 hsm_state_t * parent;
88 hsm_action_t * queue;
89};
90
91typedef struct __hsm_state hsm_state_id [];
92
111
112struct __hsm_action
113{
114 hsm_state_t * owner;
115 unsigned event;
116 hsm_state_t * target;
117 hsm_handler_t * handler;
118 hsm_action_t * next;
119};
120
121typedef struct __hsm_action hsm_action_id [];
122
126
127struct __hsm
128{
129 evq_t evq;
130 hsm_state_t * state;
131 hsm_action_t * action;
132 tsk_t * tsk;
133};
134
135typedef struct __hsm hsm_id [];
136
137/******************************************************************************
138 *
139 * Name : _HSM_STATE_INIT
140 *
141 * Description : create and initialize an hsm state object
142 *
143 * Parameters
144 * parent : pointer to parent state in the hsm tree (NULL for root)
145 *
146 * Return : hsm state object
147 *
148 * Note : for internal use
149 *
150 ******************************************************************************/
151
152#define _HSM_STATE_INIT( _parent ) \
153 { _parent, NULL }
154
159 * @param parent pointer to parent state in the hsm tree (NULL for root)
160 */
161
162#define OS_HSM_STATE( state, parent ) \
163 hsm_state_t state[] = { _HSM_STATE_INIT( parent ) }
164
165
166#define static_HSM_STATE( state, parent ) \
167 static hsm_state_t state[] = { _HSM_STATE_INIT( parent ) }
168
177 */
178
179#ifndef __cplusplus
180#define HSM_STATE_INIT( parent ) \
181 _HSM_STATE_INIT( parent )
182#endif
183
192 */
193
194#ifndef __cplusplus
195#define HSM_STATE_CREATE( parent ) \
196 { HSM_STATE_INIT ( parent ) }
197
198#define HSM_STATE_NEW \
199 HSM_STATE_CREATE
200#endif
201
202/******************************************************************************
203 *
204 * Name : _HSM_ACTION_INIT
205 *
206 * Description : create and initialize an hsm action object
207 *
208 * Parameters
209 * owner : action owner
210 * event : event value
211 * target : pointer to transition target state (NULL, if no transition)
212 * handler : event handler
213 *
214 * Return : hsm action object
215 *
216 * Note : for internal use
217 *
218 ******************************************************************************/
219
220#define _HSM_ACTION_INIT( _owner, _event, _target, _handler ) \
221 { _owner, _event, _target, _handler, NULL }
222
230 * @param handler event handler
231 */
232
233#define OS_HSM_ACTION( action, owner, event, target, handler ) \
234 hsm_action_t action[] = { _HSM_ACTION_INIT( owner, event, target, handler ) }
235
236
237#define static_HSM_ACTION( action, owner, event, target, handler ) \
238 static hsm_action_t action[] = { _HSM_ACTION_INIT( owner, event, target, handler ) }
239
251 */
252
253#ifndef __cplusplus
254#define HSM_ACTION_INIT( owner, event, target, handler ) \
255 _HSM_ACTION_INIT( owner, event, target, handler )
256#endif
257
269 */
270
271#ifndef __cplusplus
272#define HSM_ACTION_CREATE( owner, event, target, handler ) \
273 { HSM_ACTION_INIT ( owner, event, target, handler ) }
274
275#define HSM_ACTION_NEW \
276 HSM_ACTION_CREATE
277#endif
278
279/******************************************************************************
280 *
281 * Name : _HSM_INIT
282 *
283 * Description : create and initialize an hsm object
284 *
285 * Parameters
286 * limit : size of an hsm event queue (max number of stored events)
287 * data : hsm event queue data buffer
288 *
289 * Return : hsm object
290 *
291 * Note : for internal use
292 *
293 ******************************************************************************/
294
295#define _HSM_INIT( _limit, _data ) \
296 { _EVQ_INIT( _limit, _data ), NULL, NULL, NULL }
297
302 * @param limit size of an hsm event queue (max number of stored events)
303 */
304
305#define OS_HSM( hsm, limit ) \
306 static unsigned hsm##__buf[limit]; \
307 hsm_t hsm[] = { _HSM_INIT( limit, hsm##__buf ) }
308
310#define static_HSM( hsm, limit ) \
311 static unsigned hsm##__buf[limit]; \
312 static hsm_t hsm[] = { _HSM_INIT( limit, hsm##__buf ) }
313
322 */
323
324#ifndef __cplusplus
325#define HSM_INIT( limit ) \
326 _HSM_INIT( limit, _EVQ_DATA( limit ) )
327#endif
328
337 */
338
339#ifndef __cplusplus
340#define HSM_CREATE( limit ) \
341 { HSM_INIT ( limit ) }
342
343#define HSM_NEW \
344 HSM_CREATE
345#endif
346
347#ifdef __cplusplus
348extern "C" {
349#endif
350
357
358void hsm_initState( hsm_state_t *state, hsm_state_t *parent );
359
369
370void hsm_initAction( hsm_action_t *action, hsm_state_t *owner, unsigned event, hsm_state_t *target, hsm_handler_t *handler );
371
379
380void hsm_init( hsm_t *hsm, void *data, size_t bufsize );
381
392
393hsm_t *hsm_create( unsigned limit );
396__STATIC_INLINE
397hsm_t *hsm_new( unsigned limit ) { return hsm_create(limit); }
398
404
405void hsm_link( hsm_action_t *action );
406
414
415void hsm_start( hsm_t *hsm, tsk_t *tsk, hsm_state_t *initState );
417#if OS_ATOMICS
419void hsm_startAsync( hsm_t *hsm, tsk_t *tsk, hsm_state_t *initState );
420#endif
421
430
431void hsm_reset( hsm_t *hsm );
434__STATIC_INLINE
435void hsm_kill( hsm_t *hsm ) { hsm_reset(hsm); }
436
445
446void hsm_destroy( hsm_t *hsm );
449__STATIC_INLINE
450void hsm_delete( hsm_t *hsm ) { hsm_destroy(hsm); }
451
466
467int hsm_give( hsm_t *hsm, unsigned event );
470__STATIC_INLINE
471int hsm_giveISR( hsm_t *hsm, unsigned event ) { return hsm_give(hsm, event); }
473#if OS_ATOMICS
475int hsm_giveAsync( hsm_t *hsm, unsigned event );
476#endif
477
495
496int hsm_sendFor( hsm_t *hsm, unsigned event, cnt_t delay );
497
513
514int hsm_sendUntil( hsm_t *hsm, unsigned event, cnt_t time );
515
532
533__STATIC_INLINE
534int hsm_send( hsm_t *hsm, unsigned event ) { return hsm_sendFor(hsm, event, INFINITE); }
536#if OS_ATOMICS
538int hsm_sendAsync( hsm_t *hsm, unsigned event );
539#endif
540
548
549void hsm_push( hsm_t *hsm, unsigned event );
552__STATIC_INLINE
553void hsm_pushISR( hsm_t *hsm, unsigned event ) { hsm_push(hsm, event); }
554
562
563hsm_state_t *hsm_getState( hsm_t *hsm );
564
565#ifdef __cplusplus
566}
567#endif
568
569/* -------------------------------------------------------------------------- */
570
571#if defined(__cplusplus) && (__cplusplus >= 201402L) && !defined(__STATEOS_STDCXX)
572
573#include <iterator>
574#include <vector>
575
576namespace stateos {
577
579 * @brief create and initialize an hsm state object
580 */
581
582struct State : public __hsm_state
585 constexpr
586 State(): __hsm_state _HSM_STATE_INIT( nullptr) {}
587 template<class S> constexpr
589 State( S& _parent ): __hsm_state _HSM_STATE_INIT(&_parent) {}
590
592 State( State&& _src ): __hsm_state(_src)
593 {
594 assert(_src.queue == nullptr);
595 }
596
597 State( const State& ) = delete;
598 State& operator=( State&& ) = delete;
599 State& operator=( const State& ) = delete;
600};
601
602template<unsigned> struct StateMachineT; // forward declaration
603
605 * @brief create and initialize an hsm action object
606 */
607
608struct Action : public __hsm_action
610 template<class S> constexpr
612 Action( S& _owner, unsigned _event, hsm_handler_t *_handler = nullptr ): __hsm_action _HSM_ACTION_INIT(&_owner, _event, nullptr, _handler) {}
613 template<class S> constexpr
615 Action( S& _owner, unsigned _event, S& _target, hsm_handler_t *_handler = nullptr ): __hsm_action _HSM_ACTION_INIT(&_owner, _event, &_target, _handler) {}
616#if __cplusplus >= 201402L
617 template<class S, class F> constexpr
619 Action( S& _owner, unsigned _event, F&& _handler ): __hsm_action _HSM_ACTION_INIT(&_owner, _event, nullptr, handler_), handler{_handler} {}
620 template<class S, class F> constexpr
622 Action( S& _owner, unsigned _event, S& _target, F&& _handler ): __hsm_action _HSM_ACTION_INIT(&_owner, _event, &_target, handler_), handler{_handler} {}
623#endif
624
626 Action( Action&& ) = default;
628 Action( const Action& ) = default;
629 Action& operator=( Action&& ) = delete;
630 Action& operator=( const Action& ) = delete;
631
632#if __cplusplus >= 201402L
633 static
634 void handler_( hsm_t *_hsm, unsigned _event ) { static_cast<Action*>(_hsm->action)->handler(_hsm, _event); }
635 std::function<void( hsm_t *, unsigned )> handler;
636#endif
637
638 private:
639
640 void link() { hsm_link(this); }
641
642 template<unsigned>
643 friend struct StateMachineT;
644};
645
651 */
652
653template<unsigned limit_ = 1>
654struct StateMachineT : public __hsm
655{
657 StateMachineT(): __hsm _HSM_INIT(limit_, data_), tab_{} {}
659 StateMachineT( const std::vector<Action>& _tab ): __hsm _HSM_INIT(limit_, data_), tab_{_tab} {}
660
662 StateMachineT( StateMachineT&& _src ): __hsm _HSM_INIT(limit_, data_), tab_(std::move(_src.tab_))
663 {
664 assert(_src.state == nullptr && _src.evq.count == 0 && _src.evq.obj.queue == nullptr);
665 (void) _src;
666 }
667
668 StateMachineT( const StateMachineT& ) = delete;
669 StateMachineT& operator=( StateMachineT&& ) = delete;
670 StateMachineT& operator=( const StateMachineT& ) = delete;
673 template<class S, typename... A>
674 void add ( S& _owner, unsigned _event, A&&... _args ) { tab_.emplace_back(_owner, _event, std::forward<A>(_args)...); }
675 /// add the actions to the table of the state machine
676 void add ( const std::vector<Action>& _tab ) { std::copy(std::begin(_tab), std::end(_tab), std::back_inserter(tab_)); }
677
678 void start ( tsk_t& _task, hsm_state_t& _init ) { for (auto& _action: tab_) _action.link();
679 hsm_start (this, &_task, &_init); }
680 void reset () { hsm_reset (this); }
681 void kill () { hsm_kill (this); }
682 void destroy () { hsm_destroy (this); }
683 int give ( unsigned _event ) { return hsm_give (this, _event); }
684 int giveISR ( unsigned _event ) { return hsm_giveISR (this, _event); }
685 template<typename T>
686 int sendFor ( unsigned _event, const T& _delay ) { return hsm_sendFor (this, _event, Clock::count(_delay)); }
687 template<typename T>
688 int sendUntil ( unsigned _event, const T& _time ) { return hsm_sendUntil(this, _event, Clock::until(_time)); }
689 int send ( unsigned _event ) { return hsm_send (this, _event); }
690 void push ( unsigned _event ) { hsm_push (this, _event); }
691 void pushISR ( unsigned _event ) { hsm_pushISR (this, _event); }
692 hsm_state_t * getState () { return hsm_getState (this); }
693#if OS_ATOMICS
694
695 void startAsync( tsk_t& _task, hsm_state_t& _init ) { for (auto& _action: tab_) _action.link();
696 hsm_startAsync(this, &_task, &_init); }
697 int giveAsync ( unsigned _event ) { return hsm_giveAsync (this, _event); }
698 int sendAsync ( unsigned _event ) { return hsm_sendAsync (this, _event); }
699#endif
700
701#if __cplusplus >= 201402L
702 using Ptr = std::unique_ptr<StateMachineT<limit_>>;
703#else
704 using Ptr = StateMachineT<limit_> *;
705#endif
706
716 */
717
718 static
719 Ptr Create()
720 {
721 auto hsm = new (std::nothrow) StateMachineT<limit_>();
722 if (hsm != nullptr)
723 hsm->__hsm::evq.obj.res = hsm;
724 return Ptr(hsm);
725 }
728 static
729 Ptr Create( const std::vector<Action>& _tab )
730 {
731 auto hsm = new (std::nothrow) StateMachineT<limit_>(_tab);
732 if (hsm != nullptr)
733 hsm->__hsm::evq.obj.res = hsm;
734 return Ptr(hsm);
735 }
736
737 private:
738
739 unsigned data_[limit_];
740 std::vector<Action> tab_;
741};
742
743} // namespace
744#endif//__cplusplus
745
746/* -------------------------------------------------------------------------- */
747
749
750#endif//__STATEOS_HSM_H
#define INFINITE
infinite waiting
Definition osbase.h:261
char data[]
message data
Definition osmessagequeue.h:54
hsm_t * hsm_create(unsigned limit)
create and initialize a new hsm object
int hsm_give(hsm_t *hsm, unsigned event)
try to transfer event data to the hsm event queue, don't wait if the hsm event queue is full
int hsm_giveAsync(hsm_t *hsm, unsigned event)
Async alias of hsm_give().
void hsm_kill(hsm_t *hsm)
alias of hsm_reset()
Definition osstatemachine.h:432
void hsm_delete(hsm_t *hsm)
alias of hsm_destroy()
Definition osstatemachine.h:447
void hsm_reset(hsm_t *hsm)
reset the hsm object, stop the hsm event dispatcher and wake up all waiting tasks with 'E_STOPPED' ev...
int hsm_sendAsync(hsm_t *hsm, unsigned event)
Async alias of hsm_send().
void hsm_push(hsm_t *hsm, unsigned event)
transfer event data to the hsm event queue, remove the oldest event data if the hsm event queue is fu...
int hsm_send(hsm_t *hsm, unsigned event)
try to transfer event data to the hsm event queue, wait indefinitely while the hsm event queue is ful...
Definition osstatemachine.h:531
void hsm_startAsync(hsm_t *hsm, tsk_t *tsk, hsm_state_t *initState)
Async alias of hsm_start().
void hsm_link(hsm_action_t *action)
link hsm state action to the state action queue
int hsm_sendUntil(hsm_t *hsm, unsigned event, cnt_t time)
try to transfer event value to the hsm event queue, wait until given timepoint while the hsm event qu...
void hsm_pushISR(hsm_t *hsm, unsigned event)
ISR alias of hsm_push().
Definition osstatemachine.h:550
hsm_state_t * hsm_getState(hsm_t *hsm)
get current hsm state
int hsm_sendFor(hsm_t *hsm, unsigned event, cnt_t delay)
try to transfer event value to the hsm event queue, wait for given duration of time while the hsm eve...
void hsm_handler_t(hsm_t *, unsigned)
hierarchical state machine - event handler definition
Definition osstatemachine.h:79
void hsm_start(hsm_t *hsm, tsk_t *tsk, hsm_state_t *initState)
start hsm event dispatcher
void hsm_initAction(hsm_action_t *action, hsm_state_t *owner, unsigned event, hsm_state_t *target, hsm_handler_t *handler)
initialize hsm state action object
void hsm_init(hsm_t *hsm, void *data, size_t bufsize)
initialize hsm object
void hsm_initState(hsm_state_t *state, hsm_state_t *parent)
initialize hsm object
int hsm_giveISR(hsm_t *hsm, unsigned event)
ISR alias of hsm_give().
Definition osstatemachine.h:468
hsm_t * hsm_new(unsigned limit)
alias of hsm_create()
Definition osstatemachine.h:394
void hsm_destroy(hsm_t *hsm)
reset the hsm object, stop the hsm event dispatcher, wake up all waiting tasks with 'E_DELETED' event...
std::function< void(hsm_t *, unsigned)> handler
handler of the action (function object)
Definition osstatemachine.h:632
constexpr Action(S &_owner, unsigned _event, S &_target, hsm_handler_t *_handler=nullptr)
constructor, see the constructor parameters of the class
Definition osstatemachine.h:612
constexpr Action(S &_owner, unsigned _event, hsm_handler_t *_handler=nullptr)
constructor, see the constructor parameters of the class
Definition osstatemachine.h:609
constexpr Action(S &_owner, unsigned _event, S &_target, F &&_handler)
constructor, see the constructor parameters of the class
Definition osstatemachine.h:619
static constexpr rep count(const std::chrono::duration< _Rep, _Period > &_delay)
delay in ticks, rounded up to whole ticks; negative delay: IMMEDIATE, delay out of range: INFINITE
Definition osclock.h:109
static constexpr rep until(const std::chrono::time_point< Clock, _Duration > &_time)
time point in ticks, rounded up to whole ticks (only a time point of this clock)
Definition osclock.h:116
create and initialize a hierarchical state machine object
Definition osstatemachine.h:652
std::unique_ptr< StateMachineT< limit_ > > Ptr
result type of Create()
Definition osstatemachine.h:699
int sendUntil(unsigned _event, const T &_time)
hsm_sendUntil()
Definition osstatemachine.h:685
int sendAsync(unsigned _event)
hsm_sendAsync()
Definition osstatemachine.h:695
void reset()
hsm_reset()
Definition osstatemachine.h:677
void push(unsigned _event)
hsm_push()
Definition osstatemachine.h:687
int giveAsync(unsigned _event)
hsm_giveAsync()
Definition osstatemachine.h:694
int send(unsigned _event)
hsm_send()
Definition osstatemachine.h:686
StateMachineT(StateMachineT &&_src)
move constructor
Definition osstatemachine.h:659
int giveISR(unsigned _event)
hsm_giveISR()
Definition osstatemachine.h:681
void add(S &_owner, unsigned _event, A &&... _args)
add an action (parameters of the Action constructor) to the table of the state machine
Definition osstatemachine.h:671
void kill()
hsm_kill()
Definition osstatemachine.h:678
static Ptr Create()
create dynamic object with manageable resources
Definition osstatemachine.h:716
hsm_state_t * getState()
hsm_getState()
Definition osstatemachine.h:689
void startAsync(tsk_t &_task, hsm_state_t &_init)
link the actions of the table and start the state machine (hsm_startAsync())
Definition osstatemachine.h:692
int sendFor(unsigned _event, const T &_delay)
hsm_sendFor()
Definition osstatemachine.h:683
void pushISR(unsigned _event)
hsm_pushISR()
Definition osstatemachine.h:688
void start(tsk_t &_task, hsm_state_t &_init)
link the actions of the table and start the state machine (hsm_start())
Definition osstatemachine.h:675
void destroy()
hsm_destroy()
Definition osstatemachine.h:679
int give(unsigned _event)
hsm_give()
Definition osstatemachine.h:680
StateMachineT()
constructor, see the constructor parameters of the class
Definition osstatemachine.h:654
create and initialize an hsm state object
Definition osstatemachine.h:580
constexpr State()
constructor, see the constructor parameters of the class
Definition osstatemachine.h:583
constexpr State(S &_parent)
constructor, see the constructor parameters of the class
Definition osstatemachine.h:586
State(State &&_src)
move constructor
Definition osstatemachine.h:589