osstatemachine.h

/******************************************************************************
 
    @file    IntrOS: osstatemachine.h
    @author  Rajmund Szymanski
    @date    18.11.2025
    @brief   This file contains definitions for IntrOS.
 
 ******************************************************************************
 
   Copyright (c) 2018-2022 Rajmund Szymanski. All rights reserved.
 
   Permission is hereby granted, free of charge, to any person obtaining a copy
   of this software and associated documentation files (the "Software"), to
   deal in the Software without restriction, including without limitation the
   rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
   sell copies of the Software, and to permit persons to whom the Software is
   furnished to do so, subject to the following conditions:
 
   The above copyright notice and this permission notice shall be included
   in all copies or substantial portions of the Software.
 
   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
   IN THE SOFTWARE.
 
 ******************************************************************************/
 
#ifndef __INTROS_HSM_H
#define __INTROS_HSM_H
 
#include "oskernel.h"
#include "osclock.h"
#include "oseventqueue.h"

 
/* -------------------------------------------------------------------------- */
 
enum
{
    hsmALL = 0,// the state action applies to all events
    hsmStop,   // stop the state machine
    hsmExit,   // exit from the state during transition
    hsmEntry,  // entry to the state during transition
    hsmInit,   // init the state after transition
    hsmUser,   // values less than hsmUser are reserved for the system
};

 
typedef struct __hsm_state hsm_state_t;

 
typedef struct __hsm_action hsm_action_t;

 
typedef struct __hsm hsm_t;

 
typedef void hsm_handler_t(hsm_t *, unsigned);

 
struct __hsm_state
{
    hsm_state_t *   parent;  
    hsm_action_t *  queue;   
};
 
typedef struct __hsm_state hsm_state_id [];

 
struct __hsm_action
{
    hsm_state_t *   owner;   
    unsigned        event;   
    hsm_state_t *   target;  
    hsm_handler_t * handler; 
    hsm_action_t *  next;    
};
 
typedef struct __hsm_action hsm_action_id [];

 
struct __hsm
{
    evq_t           evq;     
    hsm_state_t *   state;   
    hsm_action_t *  action;  
    tsk_t *         tsk;     
};
 
typedef struct __hsm hsm_id [];
 
/******************************************************************************
 *
 * Name              : _HSM_STATE_INIT
 *
 * Description       : create and initialize an hsm state object
 *
 * Parameters
 *   parent          : pointer to parent state in the hsm tree (NULL for root)
 *
 * Return            : hsm state object
 *
 * Note              : for internal use
 *
 ******************************************************************************/
 
#define               _HSM_STATE_INIT( _parent ) \
                    { _parent, NULL }

 * @param   parent     pointer to parent state in the hsm tree (NULL for root)
 */
 
#define             OS_HSM_STATE( state, parent ) \
                       hsm_state_t state[] = { _HSM_STATE_INIT( parent ) }


#define         static_HSM_STATE( state, parent ) \
                static hsm_state_t state[] = { _HSM_STATE_INIT( parent ) }

 */
 
#ifndef __cplusplus
#define                HSM_STATE_INIT( parent ) \
                      _HSM_STATE_INIT( parent )
#endif

 */
 
#ifndef __cplusplus
#define                HSM_STATE_CREATE( parent ) \
                     { HSM_STATE_INIT  ( parent ) }

#define                HSM_STATE_NEW \
                       HSM_STATE_CREATE
#endif
 
/******************************************************************************
 *
 * Name              : _HSM_ACTION_INIT
 *
 * Description       : create and initialize an hsm action object
 *
 * Parameters
 *   owner           : action owner
 *   event           : event value
 *   target          : pointer to transition target state (NULL, if no transition)
 *   handler         : event handler
 *
 * Return            : hsm action object
 *
 * Note              : for internal use
 *
 ******************************************************************************/
 
#define               _HSM_ACTION_INIT( _owner, _event, _target, _handler ) \
                    { _owner, _event, _target, _handler, NULL }

 * @param   handler    event handler
 */
 
#define             OS_HSM_ACTION( action, owner, event, target, handler ) \
                       hsm_action_t action[] = { _HSM_ACTION_INIT( owner, event, target, handler ) }


#define         static_HSM_ACTION( action, owner, event, target, handler ) \
                static hsm_action_t action[] = { _HSM_ACTION_INIT( owner, event, target, handler ) }

 */
 
#ifndef __cplusplus
#define                HSM_ACTION_INIT( owner, event, target, handler ) \
                      _HSM_ACTION_INIT( owner, event, target, handler )
#endif

 */
 
#ifndef __cplusplus
#define                HSM_ACTION_CREATE( owner, event, target, handler ) \
                     { HSM_ACTION_INIT  ( owner, event, target, handler ) }

#define                HSM_ACTION_NEW \
                       HSM_ACTION_CREATE
#endif
 
/******************************************************************************
 *
 * Name              : _HSM_INIT
 *
 * Description       : create and initialize an hsm object
 *
 * Parameters
 *   limit           : size of an hsm event queue (max number of stored events)
 *   data            : hsm event queue data buffer
 *
 * Return            : hsm object
 *
 * Note              : for internal use
 *
 ******************************************************************************/
 
#define               _HSM_INIT( _limit, _data ) \
                    { _EVQ_INIT( _limit, _data ), NULL, NULL, NULL }

 * @param   limit      size of an hsm event queue (max number of stored events)
 */
 
#define             OS_HSM( hsm, limit )          \
                static unsigned hsm##__buf[limit]; \
                       hsm_t hsm[] = { _HSM_INIT( limit, hsm##__buf ) }

#define         static_HSM( hsm, limit )          \
                static unsigned hsm##__buf[limit]; \
                static hsm_t hsm[] = { _HSM_INIT( limit, hsm##__buf ) }

 */
 
#ifndef __cplusplus
#define                HSM_INIT( limit ) \
                      _HSM_INIT( limit, _EVQ_DATA( limit ) )
#endif

 */
 
#ifndef __cplusplus
#define                HSM_CREATE( limit ) \
                     { HSM_INIT  ( limit ) }

#define                HSM_NEW \
                       HSM_CREATE
#endif
 
#ifdef __cplusplus
extern "C" {
#endif

 
void hsm_initState( hsm_state_t *state, hsm_state_t *parent );

 
void hsm_initAction( hsm_action_t *action, hsm_state_t *owner, unsigned event, hsm_state_t *target, hsm_handler_t *handler );

 
void hsm_init( hsm_t *hsm, void *data, size_t bufsize );

 
void hsm_link( hsm_action_t *action );

 
void hsm_start( hsm_t *hsm, tsk_t *tsk, hsm_state_t *initState );
 
#if OS_ATOMICS
void hsm_startAsync( hsm_t *hsm, tsk_t *tsk, hsm_state_t *initState );
#endif

 
void hsm_reset( hsm_t *hsm );

__STATIC_INLINE
void hsm_kill( hsm_t *hsm ) { hsm_reset(hsm); }

 
int hsm_give( hsm_t *hsm, unsigned event );
 
#if OS_ATOMICS
int hsm_giveAsync( hsm_t *hsm, unsigned event );
#endif

 
int hsm_sendFor( hsm_t *hsm, unsigned event, cnt_t delay );

 
int hsm_sendUntil( hsm_t *hsm, unsigned event, cnt_t time );

 
__STATIC_INLINE
int hsm_send( hsm_t *hsm, unsigned event ) { return hsm_sendFor(hsm, event, INFINITE); }
 
#if OS_ATOMICS
int hsm_sendAsync( hsm_t *hsm, unsigned event );
#endif

 
void hsm_push( hsm_t *hsm, unsigned event );

 
hsm_state_t *hsm_getState( hsm_t *hsm );
 
#ifdef __cplusplus
}
#endif
 
/* -------------------------------------------------------------------------- */
 
#if defined(__cplusplus) && (__cplusplus >= 201402L)
 
#include <iterator>
#include <vector>
 
namespace intros {

 * @brief   create and initialize an hsm state object
 */
 
struct State : public __hsm_state
{
    constexpr
    State():             __hsm_state _HSM_STATE_INIT( nullptr) {}
    template<class S> constexpr
    State( S& _parent ): __hsm_state _HSM_STATE_INIT(&_parent) {}

    State( State&& _src ): __hsm_state(_src)
    {
        assert(_src.queue == nullptr);
    }
 
    State( const State& ) = delete;
    State& operator=( State&& ) = delete;
    State& operator=( const State& ) = delete;
};
 
template<unsigned> struct StateMachineT; // forward declaration

 * @brief   create and initialize an hsm action object
 */
 
struct Action : public __hsm_action
{
    template<class S> constexpr
    Action( S& _owner, unsigned _event,             hsm_handler_t *_handler = nullptr ): __hsm_action _HSM_ACTION_INIT(&_owner, _event,  nullptr, _handler) {}
    template<class S> constexpr
    Action( S& _owner, unsigned _event, S& _target, hsm_handler_t *_handler = nullptr ): __hsm_action _HSM_ACTION_INIT(&_owner, _event, &_target, _handler) {}
#if __cplusplus >= 201402L
    template<class S, class F> constexpr
    Action( S& _owner, unsigned _event,             F&& _handler ): __hsm_action _HSM_ACTION_INIT(&_owner, _event,  nullptr, handler_), handler{_handler} {}
    template<class S, class F> constexpr
    Action( S& _owner, unsigned _event, S& _target, F&& _handler ): __hsm_action _HSM_ACTION_INIT(&_owner, _event, &_target, handler_), handler{_handler} {}
#endif

    Action( Action&& ) = default;
    Action( const Action& ) = default;
    Action& operator=( Action&& ) = delete;
    Action& operator=( const Action& ) = delete;
 
#if __cplusplus >= 201402L
    static
    void handler_( hsm_t *_hsm, unsigned _event ) { static_cast<Action*>(_hsm->action)->handler(_hsm, _event); }
    std::function<void( hsm_t *, unsigned )> handler; 
#endif
 
    private:
 
    void link() { hsm_link(this); }
 
    template<unsigned>
    friend struct StateMachineT;
};

 */
 
template<unsigned limit_ = 1>
struct StateMachineT : public __hsm
{
    StateMachineT():                                  __hsm _HSM_INIT(limit_, data_), tab_{}     {}
    StateMachineT( const std::vector<Action>& _tab ): __hsm _HSM_INIT(limit_, data_), tab_{_tab} {}

    StateMachineT( StateMachineT&& _src ): __hsm _HSM_INIT(limit_, data_), tab_(std::move(_src.tab_))
    {
        assert(_src.state == nullptr && _src.evq.count == 0 && _src.evq.obj.queue == nullptr);
        (void) _src;
    }
 
    StateMachineT( const StateMachineT& ) = delete;
    StateMachineT& operator=( StateMachineT&& ) = delete;
    StateMachineT& operator=( const StateMachineT& ) = delete;

    template<class S, typename... A>
    void          add       ( S& _owner, unsigned _event, A&&... _args ) { tab_.emplace_back(_owner, _event, std::forward<A>(_args)...); }
    /// add the actions to the table of the state machine
    void          add       ( const std::vector<Action>& _tab )   {        std::copy(std::begin(_tab), std::end(_tab), std::back_inserter(tab_)); }

    void          start     ( tsk_t& _task, hsm_state_t& _init )  {        for (auto& _action: tab_) _action.link();
                                                                           hsm_start     (this, &_task, &_init); }
    void          reset     ()                                    {        hsm_reset     (this); }                                
    void          kill      ()                                    {        hsm_kill      (this); }                                
    int           give      ( unsigned _event )                   { return hsm_give      (this,  _event); }                       
    template<typename T>
    int           sendFor   ( unsigned _event, const T& _delay )  { return hsm_sendFor  (this,   _event, Clock::count(_delay)); } 
    template<typename T>
    int           sendUntil ( unsigned _event, const T& _time )   { return hsm_sendUntil(this,   _event, Clock::until(_time)); }  
    int           send      ( unsigned _event )                   { return hsm_send      (this,  _event); }                       
    void          push      ( unsigned _event )                   {        hsm_push      (this,  _event); }                       
    hsm_state_t * getState  ()                                    { return hsm_getState  (this); }                                
#if OS_ATOMICS

    void          startAsync( tsk_t& _task, hsm_state_t& _init )  {        for (auto& _action: tab_) _action.link();
                                                                           hsm_startAsync(this, &_task, &_init); }
    int           giveAsync ( unsigned _event )                   { return hsm_giveAsync (this,  _event); } 
    int           sendAsync ( unsigned _event )                   { return hsm_sendAsync (this,  _event); } 
#endif
 
    private:
 
    unsigned            data_[limit_];
    std::vector<Action> tab_;
};
 
}     //  namespace
#endif//__cplusplus
 
/* -------------------------------------------------------------------------- */

 
#endif//__INTROS_HSM_H