SMACH专题（四）----状态State类的实现和中文注释

SMACH中，状态（State）是状态机器组成的重要部分，理解State的原理和实现，对使用SMACH很有帮助，特别是理解

__init__(),execute(),preempt是尤为关键。

__init__()：初始化函数，状态初始化时，进行参数的初始化

execute()：状态运行时执行的函数

preempt：暂停状态

详细的说明请参考例子：The principle of Passing User Data between States

下面对State类进行解释注释，代码如下：

 import threading
 import traceback

 import smach

 __all__ = ['State','CBState']

 class State(object):
     """SMACH的状态基类

     SMACH状态和SMACH容器交互的方式有两种。第一种是它的输出标识符outcome。
     第二种是运行（execute）时，用来读入和输出打用户数据（userdata）。在execute()
     调用前，需要在构造函数（__init__()）中声明outcome和userdata并做相应的校验。
     """
     def __init__(self, outcomes=[], input_keys=[], output_keys=[], io_keys=[]):
         """状态构造函数
         @type outcomes:字符串数组
         @param outcomes: 为此状态定义输出（outcomes）.

         @type input_keys: 字符串数组
         @param input_keys: 在运行时，从外部输入的用户数据keys. 

         @type output_keys: 字符串数组
         @param output_keys: 在运行时，从外部输出的用户数据keys.

         @type io_keys: 字符串数组
         @param io_keys: 在运行时，从外部输入/输出的用户数据keys.
         """
         # 存储输出结果（outcomes）
         self._outcomes = set(outcomes)

         # 存储用户数据接口的描述
         self._input_keys = set(input_keys + io_keys)
         self._output_keys = set(output_keys + io_keys)

         # 声明暂停的标识符
         self._preempt_requested = False

     ### Meat
     def execute(self, ud):
         """Called when executing a state.当执行状态时调用
         在基类中该函数会抛出异常NotImplementedError.

         @type ud: 用户数据结构体
         @param ud: 状态在执行时，传递的用户数据
         """
         raise NotImplementedError()

     ### SMACH 接口 API
     def register_outcomes(self, new_outcomes):
         """向结果集中添加结果标签."""
         self._outcomes = self._outcomes.union(new_outcomes)

     def get_registered_outcomes(self):
         """获取已经注册打结果集.
         @rtype: 字符串数组
         @return: 已经注册打结果字符串的数组.
         """
         return tuple(self._outcomes)

     ### 用户数据API
     def register_io_keys(self, keys):
         """向io_keys集合中添加keys.
         @type keys: 字符串数组
         @param keys: 输入输出的keys.
         """
         self._input_keys = self._input_keys.union(keys)
         self._output_keys = self._output_keys.union(keys)

     def register_input_keys(self, keys):
         """向input_keys集合中添加keys.
         @type keys: 字符串列表
         @param keys: 输入的keys.
         """
         self._input_keys = self._input_keys.union(keys)

     def get_registered_input_keys(self):
         """获得已经注册的input_keys数组."""
         return tuple(self._input_keys)

     def register_output_keys(self, keys):
         """向output_keys集合中添加keys.
         @type keys: 字符串列表
         @param keys: 输出的keys.
         """
         self._output_keys = self._output_keys.union(keys)

     def get_registered_output_keys(self):
         """获得已经注册打output keys的数组."""
         return tuple(self._output_keys)

     ### 暂停的接口
     def request_preempt(self):
         """设置暂停请求preempt_requested为True，状态机暂停的时候，就需要设置该状态为False，运行时
             需要设置为True才行，否则运行到该状态就会停止了。
         """
         self._preempt_requested = True

     def service_preempt(self):
         """设置暂停请求preempt_requested为False"""
         self._preempt_requested = False

     def recall_preempt(self):
         """设置暂停请求preempt_requested为False"""
         self._preempt_requested = False

     def preempt_requested(self):
         """如果暂停则返回True."""
         return self._preempt_requested

 class CBState(State):
     def __init__(self, cb, cb_args=[], cb_kwargs={}, outcomes=[], input_keys=[], output_keys=[], io_keys=[]):
         """从一个函数中创建一个状态.

         @type outcomes: 字符串数组
         @param outcomes: 为该状态定义的outcomes.

         @type input_keys: 字符串数组
         @param input_keys: 在运行时，从外部输入的用户数据keys.  

         @type output_keys: 字符串数组
         @param output_keys: 在运行时，从外部输出的用户数据keys.

         @type io_keys: 字符串数组
         @param io_keys: 在运行时，从外部输入/输出的用户数据keys.
         """
         State.__init__(self, outcomes, input_keys, output_keys, io_keys)
         self._cb = cb
         self._cb_args = cb_args
         self._cb_kwargs = cb_kwargs

         if smach.util.has_smach_interface(cb):
             self._cb_input_keys = cb.get_registered_input_keys()
             self._cb_output_keys = cb.get_registered_output_keys()
             self._cb_outcomes = cb.get_registered_outcomes()

             self.register_input_keys(self._cb_input_keys)
             self.register_output_keys(self._cb_output_keys)
             self.register_outcomes(self._cb_outcomes)

     def execute(self, ud):
         return self._cb(ud, *self._cb_args, **self._cb_kwargs)