Tutorial 9: Coroutines

翻译自：https://www.behaviortree.dev

Async Actions using Coroutines

[使用协程的异步操作]

BehaviorTree.CPP provides two easy-to-use abstractions to create an asynchronous Action, i.e. those actions which: [BehaviorTree.CPP 提供了两个易于使用的抽象来创建异步操作，即那些操作：]

• Take a long time to be concluded. [需要很长时间才能得出结论。]
• May return “RUNNING”. [可能返回“正在运行”。]
• Can be halted. [可以暂停。]

The first class is a AsyncActionNode that executes the tick() method in a separate thread. [第一个类是 AsyncActionNode，它在单独的线程中执行 tick() 方法。]

In this tutorial, we introduce the CoroActionNode, a different action that uses coroutines to achieve similar results. [在本教程中，我们将介绍 CoroActionNode，这是一种使用协程实现类似结果的不同操作。]

The main reason is that Coroutines do not spawn a new thread and are much more efficient. Furthermore, you don’t need to worry about thread-safety in your code… [主要原因是协程不会产生新线程并且效率更高。此外，您无需担心代码中的线程安全…]

In Coroutines, the user should explicitly call a yield method when he/she wants the execution of the Action to be suspended. [在 Coroutines 中，当用户希望暂停执行 Action 时，应显式调用 yield 方法。]

CoroActionNode wraps this yield function into a convenient method setStatusRunningAndYield(). [CoroActionNode 将此 yield 函数包装到一个方便的方法 setStatusRunningAndYield() 中。]

The C++ source example

The next example can be used as a “template” for your own implementation. [下一个示例可以用作您自己实现的“模板”。]

typedef std::chrono::milliseconds Milliseconds;

class MyAsyncAction: public CoroActionNode
{
  public:
    MyAsyncAction(const std::string& name):
        CoroActionNode(name, {})
    {}

  private:
    // This is the ideal skeleton/template of an async action:
    //  - A request to a remote service provider.
    //  - A loop where we check if the reply has been received.
    //  - You may call setStatusRunningAndYield() to "pause".
    //  - Code to execute after the reply.
    //  - A simple way to handle halt().
    NodeStatus tick() override
    {
        std::cout << name() <<": Started. Send Request to server." << std::endl;

        TimePoint initial_time = Now();
        TimePoint time_before_reply = initial_time + Milliseconds(100);

        int count = 0;
        bool reply_received = false;

        while( !reply_received )
        {
            if( count++ == 0)
            {
                // call this only once
                std::cout << name() <<": Waiting Reply..." << std::endl;
            }
            // pretend that we received a reply
            if( Now() >= time_before_reply )
            {
                reply_received = true;
            }

            if( !reply_received )
            {
                // set status to RUNNING and "pause/sleep"
                // If halt() is called, we will NOT resume execution
                setStatusRunningAndYield();
            }
        }

        // This part of the code is never reached if halt() is invoked,
        // only if reply_received == true;
        std::cout << name() <<": Done. 'Waiting Reply' loop repeated "
                  << count << " times" << std::endl;
        cleanup(false);
        return NodeStatus::SUCCESS;
    }

    // you might want to cleanup differently if it was halted or successful
    void cleanup(bool halted)
    {
        if( halted )
        {
            std::cout << name() <<": cleaning up after an halt()\n" << std::endl;
        }
        else{
            std::cout << name() <<": cleaning up after SUCCESS\n" << std::endl;
        }
    }

    void halt() override
    {
        std::cout << name() <<": Halted." << std::endl;
        cleanup(true);
        // Do not forget to call this at the end.
        CoroActionNode::halt();
    }

    TimePoint Now()
    { 
        return std::chrono::high_resolution_clock::now(); 
    };
};

As you may have noticed, the action “pretends” to wait for a request message; the latter will arrive after 100 milliseconds. [您可能已经注意到，该操作“假装”等待请求消息；后者将在 100 毫秒后到达。]

To spice things up, we create a Sequence with two actions, but the entire sequence will be halted by a timeout after 150 millisecond. [为了增加趣味，我们创建了一个包含两个动作的序列，但整个序列将在 150 毫秒后因超时而暂停。]

 <root >
     <BehaviorTree>
        <Timeout msec="150">
            <SequenceStar name="sequence">
                <MyAsyncAction name="action_A"/>
                <MyAsyncAction name="action_B"/>
            </SequenceStar>
        </Timeout>
     </BehaviorTree>
 </root>

No surprises in the main()… [main() 中没有任何意外…]

int main()
{
    // Simple tree: a sequence of two asycnhronous actions,
    // but the second will be halted because of the timeout.

    BehaviorTreeFactory factory;
    factory.registerNodeType<MyAsyncAction>("MyAsyncAction");

    auto tree = factory.createTreeFromText(xml_text);

    //---------------------------------------
    // keep executing tick until it returns either SUCCESS or FAILURE
    while( tree.tickRoot() == NodeStatus::RUNNING)
    {
        tree.sleep( std::chrono::milliseconds(10) );
    }
    return 0;
}

/* Expected output:

action_A: Started. Send Request to server.
action_A: Waiting Reply...
action_A: Done. 'Waiting Reply' loop repeated 11 times
action_A: cleaning up after SUCCESS

action_B: Started. Send Request to server.
action_B: Waiting Reply...
action_B: Halted.
action_B: cleaning up after an halt()

*/