.. _stdlib_coroutines:

===========================================
协程和其他生成器支持
===========================================

.. include:: detail/coroutines.rst

COROUTINES 模块公开了协程基础设施以及其他 yielding 工具。

下面的示例说明了如何循环访问树的元素。`each_async_generator` 直接实现迭代器，其中 'yield_from' 辅助函数用于继续迭代叶子。`[coroutine]` 注解将 function 转换为 coroutine。
如果需要，函数的返回类型可以指定协程 yield type::

    require daslib/coroutines

    struct Tree
        data : int
        left, right : Tree?

    // yield from example
    def each_async_generator(tree : Tree?)
        return <- generator<int>() <|
            if tree.left != null
                yeild_from <| each_async_generator(tree.left)
            yield tree.data
            if tree.right != null
                yeild_from <| each_async_generator(tree.right)
            return false

    // coroutine as function
    [coroutine]
    def each_async(tree : Tree?) : int
        if tree.left != null
            co_await <| each_async(tree.left)
        yield tree.data
        if tree.right != null
            co_await <| each_async(tree.right)

所有函数和符号都在 “coroutines” 模块中，使用 require 来访问它。 ::

    require daslib/coroutines

++++++++++++
类型别名
++++++++++++

.. _alias-Coroutine:

.. das:attribute:: Coroutine = iterator<bool>

|typedef-coroutines-Coroutine|

.. _alias-Coroutines:

.. das:attribute:: Coroutines = array<iterator<bool>>

|typedef-coroutines-Coroutines|

++++++++++++++++++++
函数注释
++++++++++++++++++++

.. _handle-coroutines-coroutine:

.. das:attribute:: coroutine

此宏将协程函数转换为 generator，添加 return false。
协同例程的 Daslang 实施是基于生成器的。函数转换为状态机，状态机可以恢复和暂停。该函数将转换为生成器。
如果 generator 是 void 协程，则 Generator 会生成 bool，否则会生成 return 类型。
如果指定了返回类型，则协程可以用作生成器的高级形式。

+++++++++++
调用宏
+++++++++++

.. _call-macro-coroutines-co_continue:

.. das:attribute:: co_continue

此宏将 co_continue 转换为 yield true。
这个想法是，没有指定类型的协程位于产生 bool 的协程之下。
这样 co_continue() 不会分散人们对它是一个generator<bool>的注意力。
That way co_continue() does not distract from the fact that it is a generator<bool>.

.. _call-macro-coroutines-co_await:

.. das:attribute:: co_await

这个宏将co_await(sub_coroutine) 转换为::

    for t in subroutine
        yield t

这个想法是 coroutine 或 generator 可以等待 sub-coroutine 完成。

.. _call-macro-coroutines-yeild_from:

.. das:attribute:: yeild_from

此宏将 yield_from（THAT） 表达式转换为::

    for t in THAT
        yield t

这个想法是 coroutine 或 generator 可以继续从另一个子 co-routine 或 generator 中产生。

++++++++++++++++++++++++++++++
顶级协程评估
++++++++++++++++++++++++++++++

  *  :ref:`cr_run (a:iterator\<bool\> -const) : void <function-_at_coroutines_c__c_cr_run_Y_ls_Coroutine_gr_1_ls_b_gr_G>` 
  *  :ref:`cr_run_all (a:array\<iterator\<bool\>\> -const) : void <function-_at_coroutines_c__c_cr_run_all_Y_ls_Coroutines_gr_1_ls_Y_ls_Coroutine_gr_1_ls_b_gr_G_gr_A>` 

.. _function-_at_coroutines_c__c_cr_run_Y_ls_Coroutine_gr_1_ls_b_gr_G:

.. das:function:: cr_run(a: Coroutine)

+--------+------------------------------------+
+argument+argument type                       +
+========+====================================+
+a       + :ref:`Coroutine <alias-Coroutine>` +
+--------+------------------------------------+


此函数将运行协程，直到完成。

.. _function-_at_coroutines_c__c_cr_run_all_Y_ls_Coroutines_gr_1_ls_Y_ls_Coroutine_gr_1_ls_b_gr_G_gr_A:

.. das:function:: cr_run_all(a: Coroutines)

+--------+--------------------------------------+
+argument+argument type                         +
+========+======================================+
+a       + :ref:`Coroutines <alias-Coroutines>` +
+--------+--------------------------------------+


此函数运行所有协程，直到它们完成。