Coroutines
==========

.. cpp:namespace:: hysj::coroutines

In namespace :cpp:any:`coroutines`:

Proto promises
--------------

:cpp:include:`#include<hysj/coroutines/proto_promise.hpp>`


A proto-promse contains all the parameters needed by a coroutine-framework. It shall be the first parameter of the coroutine or member-coroutine. 

.. cpp:struct:: template<typename ProtoPromise> traits::return_object
.. cpp:type:: template<typename ProtoPromise> return_object

   | Specifies the type of the coroutine-return-object associated with the :cpp:expr:`ProtoPromise`.
   |

.. cpp:function:: template<typename ResumeType> auto get_proto_promise(type_t<ResumeType>,auto &promise)

   | A hook which returns a proto-promise for the given resume-type. :cpp:expr:`promise` is a reference to the promise of the current coroutine.
   |

.. cpp:struct:: template<typename ReturnObject> static_proto_promise

   .. cpp:type:: return_object = ReturnObject
   
   | Helper for coroutine-frameworks do not need any parameters passed down.
   |

.. c:macro:: HYSJ_PROMISE(proto_promise_type)

   | Returns an lvalue-reference to the coroutine-promise.
   |

Yield
-----

:cpp:include:`#include<hysj/coroutines/yield.hpp>`

.. cpp:function:: auto yield(auto &promise,auto &&... values)

Halt
----

:cpp:include:`#include<hysj/coroutines/halt.hpp>`

.. cpp:function:: auto halt(auto &promise,auto &&... values)


Bulitin
-------

.. cpp:namespace-push:: builtin

In namespace :cpp:any:`builtin`:

Trees
^^^^^

:cpp:include:`#include<hysj/coroutines/builtin/trees.hpp>`


Coroutine framework for structured and synchronous coroutines. 

.. cpp:struct:: template<typename Fruit> trees::seed

   | Proto-promise for a :cpp:type:`trees::root` coroutine.
   |
   
.. cpp:struct:: template<typename Fruit> trees::root

   | Return-object-type for the root of a coroutine-tree.
   |

.. cpp:struct:: template<typename Fruit,typename Energy> trees::sprout

   | Proto-promise for a :cpp:type:`trees::branch` coroutine.
   |

.. cpp:struct:: template<typename Fruit,typename Energy> trees::branch

   | Return-object-type for a branch of a coroutine-tree.
   |

.. cpp:struct:: template<typename Fruit> trees::root_iterator

   | Iterator-type for a coroutine-tree.
   |

.. cpp:type:: template<typename Fruit> co_seed = trees::seed<Fruit>
	      template<typename Fruit> co_root = trees::root<Fruit>
	      template<typename Fruit> co_sprout = trees::sprout<Fruit>
	      template<typename Fruit> co_branch = trees::branch<Fruit>

   | Ergonomic type-aliases.
   |

Generator
^^^^^^^^^

:cpp:include:`#include<hysj/coroutines/builtin/generator.hpp>`

Stolen from `P2168R0 <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p2168r0.pdf>`_.

.. cpp:struct:: template<typename T> generator
		
.. cpp:namespace-pop::