Fiber documentation

Co-authored-by: George Peter Banyard <girgias@php.net>
Co-authored-by: Sergey Panteleev <sergey@php.net>
Co-authored-by: Fabien Villepinte <fabien.villepinte@gmail.com>
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>

Closes GH-1096.
This commit is contained in:
Aaron Piotrowski 2021-11-27 19:49:45 +01:00 committed by Christoph M. Becker
parent 0a192fcd9c
commit 1f7a0e4af8
No known key found for this signature in database
GPG key ID: D66C9593118BCCB6
26 changed files with 1295 additions and 5 deletions

View file

@ -72,6 +72,9 @@
<listitem>
<simpara><classname>UnhandledMatchError</classname></simpara>
</listitem>
<listitem>
<simpara><classname>FiberError</classname></simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
@ -87,7 +90,7 @@
</itemizedlist>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View file

@ -25,6 +25,7 @@
&language.predefined.typeerror;
&language.predefined.valueerror;
&language.predefined.unhandledmatcherror;
&language.predefined.fibererror;
</part>
<!-- Keep this comment at the end of the file

View file

@ -0,0 +1,131 @@
<?xml version="1.0" encoding="utf-8"?>
<phpdoc:classref xml:id="class.fiber" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The Fiber class</title>
<titleabbrev>Fiber</titleabbrev>
<partintro>
<!-- {{{ Fiber intro -->
<section xml:id="fiber.intro">
&reftitle.intro;
<para>
Fibers represent full-stack, interruptible functions. Fibers may be suspended from anywhere in the call-stack,
pausing execution within the fiber until the fiber is resumed at a later time.
</para>
<para>
Fibers pause the entire execution stack, so the direct caller of the function does not need to change how it
invokes the function.
</para>
<para>
Execution may be interrupted anywhere in the call stack using <methodname>Fiber::suspend</methodname>
(that is, the call to <methodname>Fiber::suspend</methodname> may be in a deeply nested function or not
even exist at all).
</para>
<para>
Unlike stack-less <classname>Generator</classname>s, each <classname>Fiber</classname> has its own call stack,
allowing them to be paused within deeply nested function calls. A function declaring an interruption point
(that is, calling <methodname>Fiber::suspend</methodname>) need not change its return type, unlike a function using
&yield; which must return a <classname>Generator</classname> instance.
</para>
<para>
Fibers can be suspended in any function call, including those called from within the PHP VM, such as functions
provided to <function>array_map</function> or methods called by foreach on an
<classname>Iterator</classname> object.
</para>
<para>
Once suspended, execution of the fiber may be resumed with any value using <methodname>Fiber::resume</methodname>
or by throwing an exception into the fiber using <methodname>Fiber::throw</methodname>. The value is returned
(or exception thrown) from <methodname>Fiber::suspend</methodname>.
</para>
</section>
<!-- }}} -->
<section xml:id="fiber.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>Fiber</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<modifier>final</modifier>
<classname>Fiber</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.fiber')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])">
<xi:fallback/>
</xi:include>
</classsynopsis>
<!-- }}} -->
</section>
<section xml:id="fiber.examples">
<example xml:id="fiber.example.basic"><!-- {{{ -->
<title>Basic usage</title>
<programlisting role="php">
<![CDATA[
<?php
$fiber = new Fiber(function (): void {
$value = Fiber::suspend('fiber');
echo "Value used to resume fiber: ", $value, PHP_EOL;
});
$value = $fiber->start();
echo "Value from fiber suspending: ", $value, PHP_EOL;
$fiber->resume('test');
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Value from fiber suspending: fiber
Value used to resume fiber: test
]]>
</screen>
</example><!-- }}} -->
</section>
</partintro>
&language.predefined.fiber.construct;
&language.predefined.fiber.start;
&language.predefined.fiber.resume;
&language.predefined.fiber.throw;
&language.predefined.fiber.getreturn;
&language.predefined.fiber.isstarted;
&language.predefined.fiber.issuspended;
&language.predefined.fiber.isrunning;
&language.predefined.fiber.isterminated;
&language.predefined.fiber.suspend;
&language.predefined.fiber.getcurrent;
</phpdoc:classref>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,52 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::__construct</refname>
<refpurpose>Creates a new Fiber instance</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<constructorsynopsis>
<modifier>public</modifier> <methodname>Fiber::__construct</methodname>
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
</constructorsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<para>
The <type>callable</type> to invoke when starting the fiber.
Arguments given to <methodname>Fiber::start</methodname> will be
provided as arguments to the given callable.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,51 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.getcurrent" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::getCurrent</refname>
<refpurpose>Gets the currently executing Fiber instance</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>Fiber</type><type>null</type></type><methodname>Fiber::getCurrent</methodname>
<void />
</methodsynopsis>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the currently executing <classname>Fiber</classname> instance or &null; if this method is called from
outside a fiber.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,52 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.getreturn" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::getReturn</refname>
<refpurpose>Gets the value returned by the Fiber</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>Fiber::getReturn</methodname>
<void />
</methodsynopsis>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the value returned by the <type>callable</type> provided to <methodname>Fiber::__construct</methodname>.
If the fiber has not returned a value, either because it has not been started, has not terminated, or threw an
exception, a <classname>FiberError</classname> will be thrown.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.isrunning" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::isRunning</refname>
<refpurpose>Determines if the fiber is running</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Fiber::isRunning</methodname>
<void />
</methodsynopsis>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; only if the fiber is running. A fiber is considered running after a call to
<methodname>Fiber::start</methodname>, <methodname>Fiber::resume</methodname>, or
<methodname>Fiber::throw</methodname> that has not yet returned.
Return &false; if the fiber is not running.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,50 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.isstarted" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::isStarted</refname>
<refpurpose>Determines if the fiber has started</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Fiber::isStarted</methodname>
<void />
</methodsynopsis>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; only after the fiber has been started; otherwise &false; is returned.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,50 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.issuspended" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::isSuspended</refname>
<refpurpose>Determines if the fiber is suspended</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Fiber::isSuspended</methodname>
<void />
</methodsynopsis>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; if the fiber is currently suspended; otherwise &false; is returned.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,51 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.isterminated" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::isTerminated</refname>
<refpurpose>Determines if the fiber has terminated</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Fiber::isTerminated</methodname>
<void />
</methodsynopsis>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; only after the fiber has terminated, either by returning or throwing an exception;
otherwise &false; is returned.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,65 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.resume" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::resume</refname>
<refpurpose>Resumes execution of the fiber with a value</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>Fiber::resume</methodname>
<methodparam choice="opt"><type>mixed</type><parameter>value</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
Resumes the fiber using the given value as the result of the current <methodname>Fiber::suspend</methodname> call.
</para>
<para>
If the fiber is not suspended when this method is called, a <classname>FiberError</classname> will be thrown.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The value to resume the fiber. This value will be the return value of the current
<methodname>Fiber::suspend</methodname> call.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The value provided to the next call to <methodname>Fiber::suspend</methodname> or &null; if the fiber returns.
If the fiber throws an exception before suspending, it will be thrown from the call to this method.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,64 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.start" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::start</refname>
<refpurpose>Start execution of the fiber</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>Fiber::start</methodname>
<methodparam rep="repeat"><type>mixed</type><parameter>args</parameter></methodparam>
</methodsynopsis>
<para>
A variadic list of arguments to provide to the callable used when constructing the fiber.
</para>
<para>
If the fiber has already been started when this method is called, a <classname>FiberError</classname> will be thrown.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>args</parameter></term>
<listitem>
<para>
The arguments to use when invoking the callable given to the fiber constructor.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The value provided to the first call to <methodname>Fiber::suspend</methodname> or &null; if the fiber returns.
If the fiber throws an exception before suspending, it will be thrown from the call to this method.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,73 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.suspend" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::suspend</refname>
<refpurpose>Suspends execution of the current fiber</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>mixed</type><methodname>Fiber::suspend</methodname>
<methodparam choice="opt"><type>mixed</type><parameter>value</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
Suspends execution of the current fiber. The value provided to this method will be returned from the call to
<methodname>Fiber::start</methodname>, <methodname>Fiber::resume</methodname>, or
<methodname>Fiber::throw</methodname> that switched execution into the current fiber.
</para>
<para>
When the fiber is resumed, this method returns the value provided to <methodname>Fiber::resume</methodname>.
If the fiber is resumed using <methodname>Fiber::throw</methodname>, the exception given to that method will be
thrown from the call to this method.
</para>
<para>
If this method is called from outside a fiber, a <classname>FiberError</classname> will be thrown.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The value to return from the call to <methodname>Fiber::start</methodname>,
<methodname>Fiber::resume</methodname>, or <methodname>Fiber::throw</methodname> that switched execution into
the current fiber.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The value provided to <methodname>Fiber::resume</methodname>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,64 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="fiber.throw" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Fiber::throw</refname>
<refpurpose>Resumes execution of the fiber with an exception</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>Fiber::throw</methodname>
<methodparam><type>Throwable</type><parameter>exception</parameter></methodparam>
</methodsynopsis>
<para>
Resumes the fiber by throwing the given exception from the current <methodname>Fiber::suspend</methodname> call.
</para>
<para>
If the fiber is not suspended when this method is called, a <classname>FiberError</classname> will be thrown.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>exception</parameter></term>
<listitem>
<para>
The exception to throw into the fiber from the current <methodname>Fiber::suspend</methodname> call.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The value provided to the next call to <methodname>Fiber::suspend</methodname> or &null; if the fiber returns.
If the fiber throws an exception before suspending, it will be thrown from the call to this method.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,78 @@
<?xml version="1.0" encoding="utf-8"?>
<phpdoc:exceptionref xml:id="class.fibererror"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:phpdoc="http://php.net/ns/phpdoc">
<title>FiberError</title>
<titleabbrev>FiberError</titleabbrev>
<partintro>
<!-- {{{ Error intro -->
<section xml:id="fibererror.intro">
&reftitle.intro;
<para>
<ooclass><classname>FiberError</classname></ooclass> is thrown
when an invalid operation is performed on a <classname>Fiber</classname>.
</para>
</section>
<!-- }}} -->
<section xml:id="fibererror.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>FiberError</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<modifier>final</modifier>
<classname>FiberError</classname>
</ooclass>
<ooclass>
<modifier>extends</modifier>
<classname>Error</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.error')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))">
<xi:fallback />
</xi:include>
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.error')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
</partintro>
</phpdoc:exceptionref>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -19,6 +19,7 @@
&language.predefined.serializable;
&language.predefined.closure;
&language.predefined.generator;
&language.predefined.fiber;
&language.predefined.weakreference;
&language.predefined.weakmap;
&language.predefined.stringable;

View file

@ -27,6 +27,7 @@
<function name="argumentcounterror" from="PHP 7 &gt;= PHP 7.1.0, PHP 8"/>
<function name="valueerror" from="PHP 8"/>
<function name="unhandledmatcherror" from="PHP 8"/>
<function name="fibererror" from="PHP 8 &gt;= 8.1.0"/>
<function name="exception" from="PHP 5, PHP 7, PHP 8"/>
<function name="exception::__clone" from="PHP 5, PHP 7, PHP 8"/>
@ -45,7 +46,7 @@
<function name="errorexception::getseverity" from="PHP 5 &gt;= 5.1.0, PHP 7, PHP 8"/>
<function name="traversable" from="PHP 5, PHP 7, PHP 8"/>
<function name="iterator" from="PHP 5, PHP 7, PHP 8"/>
<function name="iterator::current" from="PHP 5, PHP 7, PHP 8"/>
<function name="iterator::key" from="PHP 5, PHP 7, PHP 8"/>
@ -89,6 +90,19 @@
<function name="generator::valid" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/>
<function name="generator::__wakeup" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/>
<function name="fiber" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::__construct" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::start" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::resume" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::throw" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::getreturn" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::isstarted" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::issuspended" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::isrunning" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::isterminated" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::getcurrent" from="PHP 8 &gt;= 8.1.0"/>
<function name="fiber::suspend" from="PHP 8 &gt;= 8.1.0"/>
<function name="throwable" from="PHP 7, PHP 8"/>
<function name="throwable::getmessage" from="PHP 7, PHP 8"/>
<function name="throwable::getcode" from="PHP 7, PHP 8"/>

View file

@ -45,6 +45,7 @@
&reference.reflection.reflectiontype;
&reference.reflection.reflectionuniontype;
&reference.reflection.reflectiongenerator;
&reference.reflection.reflectionfiber;
&reference.reflection.reflectionintersectiontype;
&reference.reflection.reflectionreference;
&reference.reflection.reflectionattribute;

View file

@ -0,0 +1,68 @@
<?xml version="1.0" encoding="utf-8"?>
<phpdoc:classref xml:id="class.reflectionfiber" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The ReflectionFiber class</title>
<titleabbrev>ReflectionFiber</titleabbrev>
<partintro>
<!-- {{{ ReflectionFiber intro -->
<section xml:id="reflectionfiber.intro">
&reftitle.intro;
<para>
</para>
</section>
<!-- }}} -->
<section xml:id="reflectionfiber.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>ReflectionFiber</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>ReflectionFiber</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.reflectionfiber')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.reflectionfiber')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])">
<xi:fallback/>
</xi:include>
</classsynopsis>
<!-- }}} -->
</section>
</partintro>
&reference.reflection.entities.reflectionfiber;
</phpdoc:classref>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionfiber.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionFiber::__construct</refname>
<refpurpose>Constructs a ReflectionFiber object</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<constructorsynopsis>
<modifier>public</modifier> <methodname>ReflectionFiber::__construct</methodname>
<methodparam><type>Fiber</type><parameter>fiber</parameter></methodparam>
</constructorsynopsis>
<para>
Constructs a <classname>ReflectionFiber</classname> object.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>fiber</parameter></term>
<listitem>
<para>
The <classname>Fiber</classname> to reflect.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionfiber.getcallable" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionFiber::getCallable</refname>
<refpurpose>Gets the callable used to create the Fiber</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>callable</type><methodname>ReflectionFiber::getCallable</methodname>
<void />
</methodsynopsis>
<para>
Returns the callable used to construct the <classname>Fiber</classname>. If the fiber has terminated, an
<classname>Error</classname> is thrown.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The callable used to create the <classname>Fiber</classname>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionfiber.getexecutingfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionFiber::getExecutingFile</refname>
<refpurpose>Get the file name of the current execution point</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>ReflectionFiber::getExecutingFile</methodname>
<void />
</methodsynopsis>
<para>
Returns the full path and file name of the current execution point in the reflected <classname>Fiber</classname>.
If the fiber has not been started or has terminated, an <classname>Error</classname> is thrown.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The full path and file name of the reflected fiber.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,53 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionfiber.getexecutingline" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionFiber::getExecutingLine</refname>
<refpurpose>Get the line number of the current execution point</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>int</type><methodname>ReflectionFiber::getExecutingLine</methodname>
<void />
</methodsynopsis>
<para>
Returns the line number of the current execution point in the reflected <classname>Fiber</classname>. If the fiber
has not been started or has terminated, an <classname>Error</classname> is thrown.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The line number of the current execution point in the fiber.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,52 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionfiber.getfiber" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionFiber::getFiber</refname>
<refpurpose>Get the reflected Fiber instance</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>Fiber</type><methodname>ReflectionFiber::getFiber</methodname>
<void />
</methodsynopsis>
<para>
Returns the <classname>Fiber</classname> instance being reflected.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The <classname>Fiber</classname> instance being reflected.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,96 @@
<?xml version="1.0" encoding="utf-8"?>
<refentry xml:id="reflectionfiber.gettrace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>ReflectionFiber::getTrace</refname>
<refpurpose>Get the backtrace of the current execution point</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>ReflectionFiber::getTrace</methodname>
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer><constant>DEBUG_BACKTRACE_PROVIDE_OBJECT</constant></initializer></methodparam>
</methodsynopsis>
<para>
Get the backtrace of the current execution point in the reflected <classname>Fiber</classname>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>
The value of <parameter>options</parameter> can be any of
the following flags.
</para>
<para>
<table>
<title>Available options</title>
<tgroup cols="2">
<thead>
<row>
<entry>Option</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<constant>DEBUG_BACKTRACE_PROVIDE_OBJECT</constant>
</entry>
<entry>
Default.
</entry>
</row>
<row>
<entry>
<constant>DEBUG_BACKTRACE_IGNORE_ARGS</constant>
</entry>
<entry>
Don't include the argument information for functions in the stack
trace.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The backtrace of the current execution point in the fiber.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -209,7 +209,7 @@
<function name="reflectionclass::getreflectionconstant" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
<function name="reflectionclass::getreflectionconstants" from="PHP 7 &gt;= 7.1.0, PHP 8"/>
<function name="reflectionclass::getattributes" from="PHP 8"/>
<function name="reflectionobject" from="PHP 5, PHP 7, PHP 8"/>
<function name="reflectionobject::__construct" from="PHP 5, PHP 7, PHP 8"/>
<function name="reflectionobject::__clone" from="PHP 5, PHP 7, PHP 8"/>
@ -288,6 +288,14 @@
<function name="reflectionenumbackedcase::__construct" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionenumbackedcase::getbackingvalue" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionfiber" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionfiber::__construct" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionfiber::getCallable" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionfiber::getExecutingFile" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionfiber::getExecutingLine" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionfiber::getFiber" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionfiber::getTrace" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionproperty" from="PHP 5, PHP 7, PHP 8"/>
<function name="reflectionproperty::__clone" from="PHP 5, PHP 7, PHP 8"/>
<function name="reflectionproperty::__construct" from="PHP 5, PHP 7, PHP 8"/>
@ -359,7 +367,7 @@
<function name="reflectiongenerator::getexecutingline" from="PHP 7, PHP 8"/>
<function name="reflectiongenerator::getexecutingfile" from="PHP 7, PHP 8"/>
<function name="reflectiongenerator::getexecutinggenerator" from="PHP 7, PHP 8"/>
<function name="reflectionreference" from="PHP 7 &gt;= 7.4.0, PHP 8"/>
<function name="reflectionreference::fromarrayelement" from="PHP 7 &gt;= 7.4.0, PHP 8"/>
<function name="reflectionreference::getid" from="PHP 7 &gt;= 7.4.0, PHP 8"/>
@ -376,7 +384,7 @@
<function name="reflectionuniontype::gettypes" from="PHP 8"/>
<function name="reflectionintersectiontype" from="PHP 8 &gt;= 8.1.0"/>
<function name="reflectionintersectiontype::gettypes" from="PHP 8 &gt;= 8.1.0"/>
</versions>
<!-- Keep this comment at the end of the file
Local variables: