Skip to content

Commit e0f02a3

Browse files
mumumumumumu
authored
Moved [overview|example] of Fibers to language/fibers.xml
Closes GH-1172.
1 parent 2ff6e6b commit e0f02a3

File tree

3 files changed

+89
-55
lines changed

3 files changed

+89
-55
lines changed

‎appendices/migration81/new-features.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ $arr2 = [...$arr1, 'c' => 'd']; //[1, 'a', 'c' => 'd']
8181
<title>Fibers</title>
8282

8383
<para>
84-
Support for <link linkend="class.fiber">Fibers</link> has been added.
84+
Support for <link linkend="language.fibers">Fibers</link> has been added.
8585
<!-- RFC: https://wiki.php.net/rfc/fibers -->
8686
</para>
8787
</sect3>

‎language/fibers.xml

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<chapter xml:id="language.fibers" xmlns="http://docbook.org/ns/docbook">
3+
<title>Fibers</title>
4+
5+
<simplesect xml:id="language.fibers.overview">
6+
<title>Fibers overview</title>
7+
<?phpdoc print-version-for="fiber"?>
8+
<para>
9+
Fibers represent full-stack, interruptible functions. Fibers may be suspended from anywhere in the call-stack,
10+
pausing execution within the fiber until the fiber is resumed at a later time.
11+
</para>
12+
<para>
13+
Fibers pause the entire execution stack, so the direct caller of the function does not need to change how it
14+
invokes the function.
15+
</para>
16+
<para>
17+
Execution may be interrupted anywhere in the call stack using <methodname>Fiber::suspend</methodname>
18+
(that is, the call to <methodname>Fiber::suspend</methodname> may be in a deeply nested function or not
19+
even exist at all).
20+
</para>
21+
<para>
22+
Unlike stack-less <classname>Generator</classname>s, each <classname>Fiber</classname> has its own call stack,
23+
allowing them to be paused within deeply nested function calls. A function declaring an interruption point
24+
(that is, calling <methodname>Fiber::suspend</methodname>) need not change its return type, unlike a function using
25+
&yield; which must return a <classname>Generator</classname> instance.
26+
</para>
27+
<para>
28+
Fibers can be suspended in any function call, including those called from within the PHP VM, such as functions
29+
provided to <function>array_map</function> or methods called by foreach on an
30+
<classname>Iterator</classname> object.
31+
</para>
32+
<para>
33+
Once suspended, execution of the fiber may be resumed with any value using <methodname>Fiber::resume</methodname>
34+
or by throwing an exception into the fiber using <methodname>Fiber::throw</methodname>. The value is returned
35+
(or exception thrown) from <methodname>Fiber::suspend</methodname>.
36+
</para>
37+
38+
<example xml:id="language.fiber.example.basic"><!-- {{{ -->
39+
<title>Basic usage</title>
40+
<programlisting role="php">
41+
<![CDATA[
42+
<?php
43+
$fiber = new Fiber(function (): void {
44+
$value = Fiber::suspend('fiber');
45+
echo "Value used to resume fiber: ", $value, PHP_EOL;
46+
});
47+
48+
$value = $fiber->start();
49+
50+
echo "Value from fiber suspending: ", $value, PHP_EOL;
51+
52+
$fiber->resume('test');
53+
?>
54+
]]>
55+
</programlisting>
56+
&example.outputs;
57+
<screen>
58+
<![CDATA[
59+
Value from fiber suspending: fiber
60+
Value used to resume fiber: test
61+
]]>
62+
</screen>
63+
</example><!-- }}} -->
64+
65+
</simplesect>
66+
67+
</chapter>
68+
69+
<!-- Keep this comment at the end of the file
70+
Local variables:
71+
mode: sgml
72+
sgml-omittag:t
73+
sgml-shorttag:t
74+
sgml-minimize-attributes:nil
75+
sgml-always-quote-attributes:t
76+
sgml-indent-step:1
77+
sgml-indent-data:t
78+
indent-tabs-mode:nil
79+
sgml-parent-document:nil
80+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
81+
sgml-exposed-tags:nil
82+
sgml-local-catalogs:nil
83+
sgml-local-ecat-files:nil
84+
End:
85+
vim600: syn=xml fen fdm=syntax fdl=2 si
86+
vim: et tw=78 syn=sgml
87+
vi: ts=1 sw=1
88+
-->

‎language/predefined/fiber.xml

Lines changed: 0 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -12,31 +12,6 @@
1212
Fibers represent full-stack, interruptible functions. Fibers may be suspended from anywhere in the call-stack,
1313
pausing execution within the fiber until the fiber is resumed at a later time.
1414
</para>
15-
<para>
16-
Fibers pause the entire execution stack, so the direct caller of the function does not need to change how it
17-
invokes the function.
18-
</para>
19-
<para>
20-
Execution may be interrupted anywhere in the call stack using <methodname>Fiber::suspend</methodname>
21-
(that is, the call to <methodname>Fiber::suspend</methodname> may be in a deeply nested function or not
22-
even exist at all).
23-
</para>
24-
<para>
25-
Unlike stack-less <classname>Generator</classname>s, each <classname>Fiber</classname> has its own call stack,
26-
allowing them to be paused within deeply nested function calls. A function declaring an interruption point
27-
(that is, calling <methodname>Fiber::suspend</methodname>) need not change its return type, unlike a function using
28-
&yield; which must return a <classname>Generator</classname> instance.
29-
</para>
30-
<para>
31-
Fibers can be suspended in any function call, including those called from within the PHP VM, such as functions
32-
provided to <function>array_map</function> or methods called by foreach on an
33-
<classname>Iterator</classname> object.
34-
</para>
35-
<para>
36-
Once suspended, execution of the fiber may be resumed with any value using <methodname>Fiber::resume</methodname>
37-
or by throwing an exception into the fiber using <methodname>Fiber::throw</methodname>. The value is returned
38-
(or exception thrown) from <methodname>Fiber::suspend</methodname>.
39-
</para>
4015
</section>
4116
<!-- }}} -->
4217

@@ -65,35 +40,6 @@
6540

6641
</section>
6742

68-
<section xml:id="fiber.examples">
69-
<example xml:id="fiber.example.basic"><!-- {{{ -->
70-
<title>Basic usage</title>
71-
<programlisting role="php">
72-
<![CDATA[
73-
<?php
74-
$fiber = new Fiber(function (): void {
75-
$value = Fiber::suspend('fiber');
76-
echo "Value used to resume fiber: ", $value, PHP_EOL;
77-
});
78-
79-
$value = $fiber->start();
80-
81-
echo "Value from fiber suspending: ", $value, PHP_EOL;
82-
83-
$fiber->resume('test');
84-
?>
85-
]]>
86-
</programlisting>
87-
&example.outputs;
88-
<screen>
89-
<![CDATA[
90-
Value from fiber suspending: fiber
91-
Value used to resume fiber: test
92-
]]>
93-
</screen>
94-
</example><!-- }}} -->
95-
</section>
96-
9743
</partintro>
9844

9945
&language.predefined.fiber.construct;

0 commit comments

Comments
 (0)