Name Date Size #Lines LOC

..31-Aug-2021-

.appveyor/H26-Dec-2020-

.github/workflows/H17-Mar-2021-

boost/H26-Mar-2021-

examples/H20-Jun-2021-

src/H28-Jun-2021-

stubs/H20-Jun-2021-

tests/H28-Jun-2021-

.appveyor.ymlH A D23-May-2021780 4540

.gitignoreH A D23-May-2021338 3833

.travis.ymlH A D26-Dec-2020228 2116

DockerfileH A D26-Mar-2021192 107

LICENSEH A D26-Dec-20203.1 KiB6955

Makefile.frag.w32H A D23-May-2021706 85

README.mdH A D20-Jun-20217.9 KiB198157

VagrantfileH A D26-Dec-2020481 2316

config.m4H A D30-Jun-20212.1 KiB7361

config.w32H A D23-May-2021859 2415

fiber.hH A D23-May-20214.3 KiB14882

fiber.stub.phpH A D20-Jun-20211.4 KiB6138

fiber_arginfo.hH A D20-Jun-20216.1 KiB165121

php_fiber.hH A D28-Jun-20211.7 KiB5822

vagrant-php.shH A D24-Mar-20211.1 KiB5034

README.md

1# Fiber Extension
2
3Fiber implementation for PHP using native C fibers.
4
5### Requirements
6
7- PHP 8.0 *only* (PHP 8.1+ includes Fibers, so this extension is unnecessary)
8
9## Installation
10
11Installation of the extension is similar to other PHP extensions.
12
13``` bash
14git clone https://github.com/amphp/ext-fiber
15cd ext-fiber
16phpize
17./configure
18make
19make test
20make install
21```
22
23## API
24
25Fibers are made by creating an instance of the `Fiber` class.
26
27``` php
28final class Fiber
29{
30    /**
31     * @param callable $callback Function to invoke when starting the fiber.
32     */
33    public function __construct(callable $callback) {}
34
35    /**
36     * Starts execution of the fiber. Returns when the fiber suspends or terminates.
37     *
38     * @param mixed ...$args Arguments passed to fiber function.
39     *
40     * @return mixed Value from the first suspension point or NULL if the fiber returns.
41     *
42     * @throw FiberError If the fiber has already been started.
43     * @throw Throwable If the fiber callable throws an uncaught exception.
44     */
45    public function start(mixed ...$args): mixed {}
46
47    /**
48     * Resumes the fiber, returning the given value from {@see Fiber::suspend()}.
49     * Returns when the fiber suspends or terminates.
50     *
51     * @param mixed $value
52     *
53     * @return mixed Value from the next suspension point or NULL if the fiber returns.
54     *
55     * @throw FiberError If the fiber has not started, is running, or has terminated.
56     * @throw Throwable If the fiber callable throws an uncaught exception.
57     */
58    public function resume(mixed $value = null): mixed {}
59
60    /**
61     * Throws the given exception into the fiber from {@see Fiber::suspend()}.
62     * Returns when the fiber suspends or terminates.
63     *
64     * @param Throwable $exception
65     *
66     * @return mixed Value from the next suspension point or NULL if the fiber returns.
67     *
68     * @throw FiberError If the fiber has not started, is running, or has terminated.
69     * @throw Throwable If the fiber callable throws an uncaught exception.
70     */
71    public function throw(Throwable $exception): mixed {}
72
73    /**
74     * @return bool True if the fiber has been started.
75     */
76    public function isStarted(): bool {}
77
78    /**
79     * @return bool True if the fiber is suspended.
80     */
81    public function isSuspended(): bool {}
82
83    /**
84     * @return bool True if the fiber is currently running.
85     */
86    public function isRunning(): bool {}
87
88    /**
89     * @return bool True if the fiber has completed execution (returned or threw).
90     */
91    public function isTerminated(): bool {}
92
93    /**
94     * @return mixed Return value of the fiber callback. NULL is returned if the fiber does not have a return statement.
95     *
96     * @throws FiberError If the fiber has not terminated or the fiber threw an exception.
97     */
98    public function getReturn(): mixed {}
99
100    /**
101     * @return self|null Returns the currently executing fiber instance or NULL if in {main}.
102     */
103    public static function getCurrent(): ?self {}
104
105    /**
106     * Suspend execution of the fiber. The fiber may be resumed with {@see Fiber::resume()} or {@see Fiber::throw()}.
107     *
108     * Cannot be called from {main}.
109     *
110     * @param mixed $value Value to return from {@see Fiber::resume()} or {@see Fiber::throw()}.
111     *
112     * @return mixed Value provided to {@see Fiber::resume()}.
113     *
114     * @throws FiberError Thrown if not within a fiber (i.e., if called from {main}).
115     * @throws Throwable Exception provided to {@see Fiber::throw()}.
116     */
117    public static function suspend(mixed $value = null): mixed {}
118}
119```
120
121A `Fiber` object is created using `new Fiber(callable $callback)` with any callable. The callable need not call `Fiber::suspend()` directly, it may be in a deeply nested call, far down the call stack (or perhaps never call `Fiber::suspend()` at all). The returned `Fiber` may be started using `Fiber->start(mixed ...$args)` with a variadic argument list that is provided as arguments to the callable used when creating the `Fiber`.
122
123`Fiber::suspend()` suspends execution of the current fiber and returns execution to the call to `Fiber->start()`, `Fiber->resume()`, or `Fiber->throw()`. The value passed to `Fiber::suspend()` is used as the return value of these methods. If the fiber throws an exception, the exception is thrown from the call to these methods. `Fiber::suspend()` will throw an instance of `FiberError` if called outside a fiber (i.e., if called from `{main}`).
124
125A suspended fiber may be resumed in one of two ways:
126
127* returning a value from `Fiber::suspend()` using `Fiber->resume()`
128* throwing an exception from `Fiber::suspend()` using `Fiber->throw()`
129
130`Fiber->getReturn()` returns the value returned from a terminated fiber (`NULL` is returned if the fiber did not return a value). This function will throw an instance of `FiberError` if the fiber has not completed execution or threw an exception.
131
132`Fiber::getCurrent()` returns the currently executing `Fiber` instance or `NULL` if called from `{main}`. This allows a fiber to store a reference to itself elsewhere, such as within an event loop callback or an array of awaiting fibers.
133
134---
135
136### ReflectionFiber
137
138`ReflectionFiber` is used to inspect executing fibers. A `ReflectionFiber` object can be created from any `Fiber` object, even if it has not been started or if it has been finished. This reflection class is similar to `ReflectionGenerator`.
139
140``` php
141final class ReflectionFiber
142{
143    /**
144     * @param Fiber $fiber Any Fiber object, including those that are not started or have
145     *                     terminated.
146     */
147    public function __construct(Fiber $fiber) {}
148
149    /**
150     * @return Fiber The reflected Fiber object.
151     */
152    public function getFiber(): Fiber {}
153
154    /**
155     * @return string Current file of fiber execution.
156     *
157     * @throws Error If the fiber has not been started or has terminated.
158     */
159    public function getExecutingFile(): string {}
160
161    /**
162     * @return int Current line of fiber execution.
163     *
164     * @throws Error If the fiber has not been started or has terminated.
165     */
166    public function getExecutingLine(): int {}
167
168    /**
169     * @param int $options Same flags as {@see debug_backtrace()}.
170     *
171     * @return array Fiber backtrace, similar to {@see debug_backtrace()}
172     *               and {@see ReflectionGenerator::getTrace()}.
173     *
174     * @throws Error If the fiber has not been started or has terminated.
175     */
176    public function getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT): array {}
177
178    /**
179     * @return callable Callable used to create the fiber.
180     *
181     * @throws Error If the fiber has been terminated.
182     */
183    public function getCallable(): callable {}
184}
185```
186
187#### Unfinished Fibers
188
189Fibers that are not finished (do not complete execution) are destroyed similarly to unfinished generators, executing any pending `finally` blocks. `Fiber::suspend()` may not be invoked in a force-closed fiber, just as `yield` cannot be used in a force-closed generator. Fibers are destroyed when there are no references to the `Fiber` object.
190
191#### Fiber Stacks
192
193Each fiber is allocated a separate C stack and VM stack on the heap. The C stack is allocated using `mmap` if available, meaning physical memory is used only on demand (if it needs to be allocated to a stack value) on most platforms. Each fiber stack is allocated a maximum of 8M of memory by default, settable with an ini setting `fiber.stack_size`. Note that this memory is used for the C stack and is not related to the memory available to PHP code. VM stacks for each fiber are allocated in a similar way to generators and use a similar amount of memory and CPU. VM stacks are able to grow dynamically, so only a single VM page (4K) is initially allocated.
194
195## PHP 8.1+
196
197This extension *only* works with PHP 8.0. The [Fiber RFC](https://wiki.php.net/rfc/fibers) was accepted and will be a part of PHP 8.1, so this extension is not necessary and incompatible with PHP 8.1 and above.
198