Add NEWS/UPGRADING and some implementation notes

NEWS

@@ -78,6 +78,7 @@
   . Implemented the RFC `Continue Output Buffering`. (Mike)
   . Implemented the RFC `Constructor behaviour of internal classes`. (Dan, Dmitry)
   . Implemented the RFC `Fix "foreach" behavior`. (Dmitry)
+  . Implemented the RFC `Generator Delegation`. (Bob)
 
 - Curl:
   . Fixed bug #68937 (Segfault in curl_multi_exec). (Laruence)

UPGRADING

@@ -499,6 +499,8 @@ Other
   . define() now supports arrays as constant values, fixing an oversight where define() did not support arrays yet const syntax did.
   . Added the comparison operator (<=>), aka the spaceship operator.
     (RFC: https://wiki.php.net/rfc/combined-comparison-operator)
+  . Added the yield from operator for delegating Generators like coroutines.
+    (RFC: https://wiki.php.net/rfc/generator-delegation)
 
 - OpenSSL
   . Added "alpn_protocols" SSL context option allowing encrypted client/server

Zend/zend_generators.h

@@ -30,10 +30,18 @@ extern ZEND_API zend_class_entry *zend_ce_ClosedGeneratorException;
 typedef struct _zend_generator_node zend_generator_node;
 typedef struct _zend_generator zend_generator;
 
+/* The concept of `yield from` exposes problems when accessed at different levels of the chain of delegated generators. We need to be able to reference the currently executed Generator in all cases and still being able to access the return values of finished Generators.  
+ * The solution to this problem is a doubly-linked tree, which all Generators referenced in maintain a reference to. It should be impossible to avoid walking the tree in all cases. This way, we only need tree walks from leaf to root in case where some part of the `yield from` chain is passed to another `yield from`. (Update of leaf node pointer and list of multi-children nodes needed when leaf gets a child in direct path from leaf to root node.) But only in that case, which should be a fairly rare case (which is then possible, but not totally cheap).
+ * The root of the tree is then the currently executed Generator. The subnodes of the tree (all except the root node) are all Generators which do `yield from`. Each node of the tree knows a pointer to one leaf descendant node. Each node with multiple children needs a list of all leaf descendant nodes paired with pointers to their respective child node. (The stack is determined by leaf node pointers) Nodes with only one child just don't need a list, there it is enough to just have a pointer to the child node. Further, leaf nodes store a pointer to the root node.
+ * That way, when we advance any generator, we just need to look up a leaf node (which all have a reference to a root node). Then we can see at the root node whether current Generator is finished. If it isn't, all is fine and we can just continue. If the Generator finished, there will be two cases. Either it is a simple node with just one child, then go down to child node. Or it has multiple children and we now will remove the current leaf node from the list of nodes (unnecessary, is microoptimization) and go down to the child node whose reference was paired with current leaf node. Child node is then removed its parent reference and becomes new top node. Or the current node references the Generator we're currently executing, then we can continue from the YIELD_FROM opcode. When a node referenced as root node in a leaf node has a parent, then we go the way up until we find a root node without parent.
+ * In case we go into a new `yield from` level, a node is created on top of current root and becomes the new root. Leaf node needs to be updated with new root node then.
+ * When a Generator referenced by a node of the tree is added to `yield from`, that node now gets a list of children (we need to walk the descendants of that node and nodes of the tree of the other Generator down to the first multi-children node and copy all the leaf node pointers from there). In case there was no multi-children node (linear tree), we just add a pair (pointer to leaf node, pointer to child node), with the child node being in a direct path from leaf to this node.
+ */
+
 struct _zend_generator_node {
 	zend_generator *parent; /* NULL for root */
 	uint32_t children;
-	union {
+	union { /* HashTable / hard coded array for faster access */
 		HashTable ht; /* if > 4 children */
 		struct {
 			zend_generator *leaf;