chsm.h

Go to the documentation of this file.

/*
**      CHSM Language System
**      chsm.h -- Run-Time library declarations
**
**      Copyright (C) 1996-2010  Paul J. Lucas & Fabio Riccardi
**
**      This program is free software; you can redistribute it and/or modify
**      it under the terms of the GNU General Public License as published by
**      the Free Software Foundation; either version 2 of the License, or
**      (at your option) any later version.
** 
**      This program is distributed in the hope that it will be useful,
**      but WITHOUT ANY WARRANTY; without even the implied warranty of
**      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
**      GNU General Public License for more details.
** 
**      You should have received a copy of the GNU General Public License
**      along with this program; if not, write to the Free Software
**      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/

#ifndef chsm_H
#define chsm_H

// standard
#include <list>
#ifdef  CHSM_MULTITHREADED
#include <pthread.h>
#endif

#define CHSM_NS Concurrent_Hierarchical_State_Machine

namespace CHSM_NS {
    class   machine;
    class   state;
    class   parent;
    class   cluster;
    class   set;
    class   event;
    struct  transition;

// macros to aid in argument-lists
#define CHSM_FORMAL(X)  X
#define CHSM_ACTUAL(X)  /* nothing */

#ifdef  CHSM_MULTITHREADED

class mutex_lock {
public:
    mutex_lock( pthread_mutex_t &m );

    ~mutex_lock();

private:
    int prev_cancel_state_;
    pthread_mutex_t &mutex_;

    mutex_lock( mutex_lock& );                  // forbid copy
    mutex_lock& operator=( mutex_lock const& ); // forbid assignment
};


inline mutex_lock::mutex_lock( pthread_mutex_t &m ) : mutex_( m ) {
    pthread_setcancelstate( PTHREAD_CANCEL_DISABLE, &prev_cancel_state_ );
    pthread_mutex_lock( &mutex_ );
}

inline mutex_lock::~mutex_lock() {
    pthread_mutex_unlock( &mutex_ );
    pthread_setcancelstate( prev_cancel_state_, 0 );
    pthread_testcancel();
}
#endif  /* CHSM_MULTITHREADED */

//=============================================================================

class state {
public:
    //
    // The constructor arguments must have horribly long names to avoid a name
    // collision with user-defined state names in the mem-initializers in the
    // resultant C++ code.  We use macros to make life easier.
    //
#   define  CHSM_STATE_ARG_LIST(A) \
            A(CHSM_NS::machine&) chsm_machine_, \
            A(char const*) chsm_name_, \
            A(CHSM_NS::parent*) chsm_parent_, \
            A(CHSM_NS::state::action) chsm_enter_action_, \
            A(CHSM_NS::state::action) chsm_exit_action_, \
            A(CHSM_NS::event*) chsm_enter_event_, \
            A(CHSM_NS::event*) chsm_exit_event_

#   define  CHSM_STATE_ARGS CHSM_STATE_ARG_LIST(CHSM_FORMAL)

#   define  CHSM_STATE_INIT CHSM_STATE_ARG_LIST(CHSM_ACTUAL)

    typedef int id;

    typedef void (machine::*action)( state const &s, event const &trigger );

    state( CHSM_STATE_ARGS );

    ~state();

    bool active() const             { return state_ & S_active; }

    virtual void deep_clear();

    char const* name() const        { return name_; }

    parent* parent_of() const       { return parent_; }

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

protected:
    machine &machine_;

    virtual bool enter( event const &trigger, state *from_child = 0 );

    virtual bool exit( event const &trigger, state *to = 0 );

private:
    char const  *const name_;       
    parent      *const parent_;     

    enum {
        S_inactive          = 0x00,
        S_active            = 0x01,
        //
        // S_active_disabled is used to prevent making more than one
        // nondeterministic transition from the same state.  See the comments
        // in event.c for more information.
        //
        S_active_disabled   = 0x02 | S_active
    };
    unsigned state_;                

    event *const enter_event_, *const exit_event_;

    action const enter_action_, exit_action_;

    friend class cluster;
    friend class event;
    friend class machine;
    friend class parent;
    friend class set;
};

//=============================================================================

struct transition {
    typedef bool (machine::*condition)( event const &trigger );

    typedef void (machine::*action)( event const &trigger );

    typedef state* (machine::*target)( event const &trigger );

    condition   condition_;

    state::id   from_id_;

    state::id   to_id_;

    target      target_;

    action      action_;

    bool        is_internal() const;

    static bool is_legal( state const *s1, state const *s2 );
};

//=============================================================================

class event {
protected:
    /*
    ** Note: Even though this section is protected (as opposed to private), it
    ** is so that derived classes emitted by the CHSM-to-C++ compiler will have
    ** access and it is not the intent that end users will.
    */

    //
    // These typedefs are placed up here because they are used in the
    // CHSM_EVENT_ARGS macro used in event's constructor.
    //
    typedef int transition_id;
    typedef transition_id const *transition_list;

    machine &machine_;

public:
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#   define  CHSM_EVENT_ARG_LIST(A) \
            A(CHSM_NS::machine*) chsm_machine_, \
            A(transition_list) chsm_transition_list_, \
            A(char const*) chsm_name_, \
            A(CHSM_NS::event*) chsm_base_event_

#   define  CHSM_EVENT_ARGS CHSM_EVENT_ARG_LIST(CHSM_FORMAL)

#   define  CHSM_EVENT_INIT CHSM_EVENT_ARG_LIST(CHSM_ACTUAL)

    event( CHSM_EVENT_ARGS );

    virtual ~event();

    void operator()()               { lock_broadcast(); }

    template<typename EventClass> bool is_type() const {
        return dynamic_cast<EventClass const*>( this );
    }

    char const* name() const        { return name_; }

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

public:
    /*
    ** Note: Even though this section is public (as opposed to private), it
    ** is so that code emitted by the CHSM-to-C++ compiler will have access and
    ** it is not the intent that end users will.
    */

    struct param_block;
    friend struct param_block;

    struct param_block {
        param_block( event const &e ) : chsm_event_( e ) { }

        virtual ~param_block();

    protected:
        /*
        ** Note: Even though this section is protected (as opposed to private),
        ** it is so that derived classes emitted by the CHSM-to-C++ compiler
        ** will have access and it is not the intent that end users will.
        */

        event const &chsm_event_;

        machine& chsm() const       { return chsm_event_.machine_; }

        virtual bool precondition() const;

        friend class event;
    };

protected:
    /*
    ** Note: Even though this section is protected (as opposed to private),
    ** it is so that derived classes emitted by the CHSM-to-C++ compiler will
    ** have access and it is not the intent that end users will.
    */

    unsigned in_progress_;

    void *param_block_;

    void broadcast( void *param_block );

#ifdef  CHSM_MULTITHREADED

    class machine_lock : public mutex_lock {
    public:
        machine_lock( machine& );
    };
#endif  /* CHSM_MULTITHREADED */

private:
    transition_list const   transitions_;

    char const              *const name_;       
    event                   *const base_event_; 
    static int const        no_transition_id_;  

    bool empty() const;

    void lock_broadcast();

    typedef transition value_type;

    typedef value_type const* const_pointer;

    typedef value_type const& const_reference;

    class const_iterator;
    friend class const_iterator;

    class const_iterator {
    public:
        const_iterator() { }

        transition_id id() const            { return *t_id_; }

        const_reference operator*() const   { return t_[ *t_id_ ]; }

        const_pointer operator->() const    { return &operator*(); }

        const_iterator& operator++() {
            ++t_id_;
            bump();
            return *this;
        }

        const_iterator operator++(int) {
            const_iterator const temp = *this;
            ++*this;
            return temp;
        }

        friend bool operator==( const_iterator const &i,
                                const_iterator const &j ) {
            return *i.t_id_ == *j.t_id_;
        }

        friend bool operator!=( const_iterator const &i,
                                const_iterator const &j ) {
            return !( i == j );
        }

    protected:
        const_pointer   t_;             // machine's transitions
        transition_list t_id_;
        event const     *base_event_;

        const_iterator( const_pointer, transition_list, event const* );

    private:
        void bump();

        friend class event;
    };

    const_iterator begin() const;

    const_iterator end() const {
        return const_iterator( 0, &no_transition_id_, 0 );
    }

    void broadcasted();

    friend class    machine;
    friend bool     state::enter( event const&, state* );
    friend bool     state::exit ( event const&, state* );
};


inline bool event::empty() const {
    return *transitions_ == no_transition_id_;
}

inline bool operator==( event const &a, event const &b ) {
    return &a == &b;
}

inline bool operator!=( event const &a, event const &b ) {
    return !( a == b );
}

//=============================================================================

class machine {
    static event prime_;

public:
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    //
    // The constructor arguments must have horribly long names to avoid a
    // name collision with user-defined constructor arguments in derived
    // classes.  We use macros to make life easier.
    //
#   define  CHSM_MACHINE_ARG_LIST(A) \
            A(CHSM_NS::state*) chsm_state_ A([]), \
            A(CHSM_NS::cluster&) chsm_root_, \
            A(CHSM_NS::transition const) chsm_transition_ A([]), \
            A(CHSM_NS::event const*) chsm_taken_ A([]), \
            A(CHSM_NS::state*) chsm_target_ A([]), \
            A(int) chsm_transitions_in_machine_

#   define CHSM_MACHINE_ARGS    CHSM_MACHINE_ARG_LIST(CHSM_FORMAL)

#   define CHSM_MACHINE_INIT    CHSM_MACHINE_ARG_LIST(CHSM_ACTUAL)

    virtual ~machine();

    bool active() const;

    virtual bool enter( event const &trigger = prime_ );

    virtual bool exit( event const &trigger = prime_ );

    typedef state value_type;

    typedef value_type const* const_pointer;

    typedef value_type const& const_reference;

    class const_iterator {
    public:
        const_iterator() { }

        const_reference operator*() const  { return **p_; }

        const_pointer operator->() const    { return *p_; }

        const_iterator& operator++()        { return ++p_, *this; }

        const_iterator operator++(int)      { return const_iterator( p_++ ); }

        friend bool operator==( const_iterator const &i,
                                const_iterator const &j ) {
            return *i.p_ == *j.p_;
        }

        friend bool operator!=( const_iterator const &i,
                                const_iterator const &j ) {
            return !( i == j );
        }

    private:
        typedef const_pointer const *iter_type;
        iter_type p_;
        const_iterator( iter_type p ) : p_( p ) { }
        friend class machine;
    };

    const_iterator begin() const {
        return const_iterator( (const_iterator::iter_type)state_ );
    }

    const_iterator end() const {
        return const_iterator( (const_iterator::iter_type)&nil_ );
    }

    enum {
        D_none  = 0x00,

        D_enex  = 0x01,

        D_event = 0x02,

        D_alg   = 0x04,

        D_all   = D_enex | D_event | D_alg
    };

    unsigned debug() const          { return debug_; }

    unsigned debug( unsigned state ) {
        unsigned const temp = debug_;
        debug_ = state;
        return temp;
    }

    void dump_state() const;

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

protected:
    machine( CHSM_MACHINE_ARGS );

private:
    typedef std::list<event*> event_queue;

    state *const *const state_;

    cluster &root_;

    transition const *const transition_;

    int const transitions_in_machine_;

    event const **const taken_;

    state **const target_;

    bool in_progress_;

    event_queue         event_queue_;   
    unsigned            debug_;         
    static void         *const nil_;    
    static int const    no_state_id_;   

#ifdef  CHSM_MULTITHREADED
    mutable pthread_mutex_t machine_lock_;
#endif

    void algorithm();

    friend class event;
    friend class event::machine_lock;
    friend class parent;
    friend struct transition;
};

//=============================================================================

class parent : public state {
protected:
    typedef int const* child_list;

public:
#   define  CHSM_PARENT_ARG_LIST(A) \
            CHSM_STATE_ARG_LIST(A), \
            A(child_list) chsm_children_

#   define  CHSM_PARENT_ARGS    CHSM_PARENT_ARG_LIST(CHSM_FORMAL)

#   define  CHSM_PARENT_INIT    CHSM_PARENT_ARG_LIST(CHSM_ACTUAL)

    typedef state value_type;

    typedef value_type* pointer;

    typedef value_type const* const_pointer;

    typedef value_type& reference;

    typedef value_type const& const_reference;

    virtual void deep_clear();

    bool empty() const              { return *children_ == no_child_id_; }

    reference front()               { return *(machine_.state_)[*children_]; }

    const_reference front() const   { return *(machine_.state_)[*children_]; }

    class iterator;
    friend class iterator;

    class iterator {
    public:
        iterator() { }

        reference operator* () const        { return *p_[ *c_ ]; }

        pointer operator->() const          { return  p_[ *c_ ]; }

        iterator& operator++() {
            return ++c_, *this;
        }

        iterator operator++(int) {
            return iterator( p_, c_++ );
        }

        friend bool operator==( iterator const &i, iterator const &j ) {
            return *i.c_ == *j.c_;
        }

        friend bool operator!=( iterator const &i, iterator const &j ) {
            return !( i == j );
        }

    protected:
        pointer const   *p_;
        child_list      c_;
        iterator( pointer const *p, child_list c ) : p_( p ), c_( c ) { }
        friend class    parent;
    };

    iterator begin() {
        return iterator( machine_.state_, children_ );
    }

    iterator end() {
        return iterator( 0, &no_child_id_ );
    }

    class const_iterator;
    friend class const_iterator;

    class const_iterator {
    public:
        const_iterator() { }

        const_reference operator*() const   { return *p_[ *c_ ]; }

        const_pointer operator->() const    { return  p_[ *c_ ]; }

        const_iterator& operator++() {
            return ++c_, *this;
        }

        const_iterator operator++(int) {
            return const_iterator( p_, c_++ );
        }

        friend bool operator==( const_iterator const &i,
                                const_iterator const &j ) {
            return *i.c_ == *j.c_;
        }

        friend bool operator!=( const_iterator const &i,
                                const_iterator const &j ) {
            return !( i == j );
        }

    protected:
        pointer const   *p_;
        child_list      c_;
        const_iterator( pointer const *p, child_list c ) : p_( p ), c_( c ) { }
        friend class    parent;
    };

    const_iterator begin() const {
        return const_iterator( machine_.state_, children_ );
    }

    const_iterator end() const {
        return const_iterator( 0, &no_child_id_ );
    }

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

protected:
    parent( CHSM_PARENT_ARGS );

    virtual bool switch_child( state *child );

    // for access to switch_child()
    friend bool state::enter( event const&, state* );

private:
    child_list const    children_;      
    static int const    no_child_id_;   
};

//=============================================================================

class cluster : public parent {
public:
#   define  CHSM_CLUSTER_ARG_LIST(A) \
            CHSM_PARENT_ARG_LIST(A), \
            A(bool) chsm_history_

#   define  CHSM_CLUSTER_ARGS   CHSM_CLUSTER_ARG_LIST(CHSM_FORMAL)

#   define  CHSM_CLUSTER_INIT   CHSM_CLUSTER_ARG_LIST(CHSM_ACTUAL)

    cluster( CHSM_CLUSTER_ARGS );

    void clear()                    { last_child_ = &front(); }

    virtual void deep_clear();

    virtual bool enter( event const &trigger, state *from_child = 0 );

    virtual bool exit( event const &trigger, state *to = 0 );

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

private:
    bool const  history_;           // do we have a history?
    state       *active_child_, *last_child_;

    // inherited
    virtual bool switch_child( state* );
};

//=============================================================================

class set : public parent {
public:
#   define  CHSM_SET_ARG_LIST(A) \
            CHSM_PARENT_ARG_LIST(A)

#   define  CHSM_SET_ARGS   CHSM_SET_ARG_LIST(CHSM_FORMAL)

#   define  CHSM_SET_INIT   CHSM_SET_ARG_LIST(CHSM_ACTUAL)

    set( CHSM_SET_ARGS ) : parent( CHSM_PARENT_INIT ) { }

    virtual bool enter( event const &trigger, state *from_child = 0 );

    virtual bool exit( event const &trigger, state *to = 0 );
};


inline event::const_iterator event::begin() const {
    //
    // This has to be defined down here so that the declaration for the machine
    // class has been seen by the C++ compiler.
    //
    return const_iterator( machine_.transition_, transitions_, base_event_ );
}

#ifdef  CHSM_MULTITHREADED
inline event::machine_lock::machine_lock( machine &m ) :
    mutex_lock( m.machine_lock_ )
{
}
#endif  /* CHSM_MULTITHREADED */

inline bool machine::active() const {
    //
    // A machine as a whole is active only if its root cluster is.
    //
    return root_.active();
}

inline bool transition::is_internal() const {
    return to_id_ == machine::no_state_id_ && !target_;
}

} // namespace


#ifndef CHSM_NO_ALIAS_NS

#   ifndef  CHSM_NS_ALIAS
#   define  CHSM_NS_ALIAS CHSM
#   endif

namespace CHSM_NS_ALIAS = CHSM_NS;

#endif  /* CHSM_NO_ALIAS_NS */

#endif  /* chsm_H */
/* vim:set et sw=4 ts=4: */