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)