README.md
1# Fiber Extension
2
3Fiber implementation for PHP using native C fibers.
4
5> **Warning**
6> Please upgrade to PHP 8.1 instead of using this extension. There are subtle differences, which can't be fixed in the extension.
7
8### Requirements
9
10- PHP 8.0 *only* (PHP 8.1+ includes Fibers, so this extension is unnecessary)
11
12## Installation
13
14Installation of the extension is similar to other PHP extensions.
15
16``` bash
17git clone https://github.com/amphp/ext-fiber
18cd ext-fiber
19phpize
20./configure
21make
22make test
23make install
24```
25
26## API
27
28Fibers are made by creating an instance of the `Fiber` class.
29
30``` php
31final class Fiber
32{
33 /**
34 * @param callable $callback Function to invoke when starting the fiber.
35 */
36 public function __construct(callable $callback) {}
37
38 /**
39 * Starts execution of the fiber. Returns when the fiber suspends or terminates.
40 *
41 * @param mixed ...$args Arguments passed to fiber function.
42 *
43 * @return mixed Value from the first suspension point or NULL if the fiber returns.
44 *
45 * @throw FiberError If the fiber has already been started.
46 * @throw Throwable If the fiber callable throws an uncaught exception.
47 */
48 public function start(mixed ...$args): mixed {}
49
50 /**
51 * Resumes the fiber, returning the given value from {@see Fiber::suspend()}.
52 * Returns when the fiber suspends or terminates.
53 *
54 * @param mixed $value
55 *
56 * @return mixed Value from the next suspension point or NULL if the fiber returns.
57 *
58 * @throw FiberError If the fiber has not started, is running, or has terminated.
59 * @throw Throwable If the fiber callable throws an uncaught exception.
60 */
61 public function resume(mixed $value = null): mixed {}
62
63 /**
64 * Throws the given exception into the fiber from {@see Fiber::suspend()}.
65 * Returns when the fiber suspends or terminates.
66 *
67 * @param Throwable $exception
68 *
69 * @return mixed Value from the next suspension point or NULL if the fiber returns.
70 *
71 * @throw FiberError If the fiber has not started, is running, or has terminated.
72 * @throw Throwable If the fiber callable throws an uncaught exception.
73 */
74 public function throw(Throwable $exception): mixed {}
75
76 /**
77 * @return bool True if the fiber has been started.
78 */
79 public function isStarted(): bool {}
80
81 /**
82 * @return bool True if the fiber is suspended.
83 */
84 public function isSuspended(): bool {}
85
86 /**
87 * @return bool True if the fiber is currently running.
88 */
89 public function isRunning(): bool {}
90
91 /**
92 * @return bool True if the fiber has completed execution (returned or threw).
93 */
94 public function isTerminated(): bool {}
95
96 /**
97 * @return mixed Return value of the fiber callback. NULL is returned if the fiber does not have a return statement.
98 *
99 * @throws FiberError If the fiber has not terminated or the fiber threw an exception.
100 */
101 public function getReturn(): mixed {}
102
103 /**
104 * @return self|null Returns the currently executing fiber instance or NULL if in {main}.
105 */
106 public static function getCurrent(): ?self {}
107
108 /**
109 * Suspend execution of the fiber. The fiber may be resumed with {@see Fiber::resume()} or {@see Fiber::throw()}.
110 *
111 * Cannot be called from {main}.
112 *
113 * @param mixed $value Value to return from {@see Fiber::resume()} or {@see Fiber::throw()}.
114 *
115 * @return mixed Value provided to {@see Fiber::resume()}.
116 *
117 * @throws FiberError Thrown if not within a fiber (i.e., if called from {main}).
118 * @throws Throwable Exception provided to {@see Fiber::throw()}.
119 */
120 public static function suspend(mixed $value = null): mixed {}
121}
122```
123
124A `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`.
125
126`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}`).
127
128A suspended fiber may be resumed in one of two ways:
129
130* returning a value from `Fiber::suspend()` using `Fiber->resume()`
131* throwing an exception from `Fiber::suspend()` using `Fiber->throw()`
132
133`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.
134
135`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.
136
137---
138
139### ReflectionFiber
140
141`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`.
142
143``` php
144final class ReflectionFiber
145{
146 /**
147 * @param Fiber $fiber Any Fiber object, including those that are not started or have
148 * terminated.
149 */
150 public function __construct(Fiber $fiber) {}
151
152 /**
153 * @return Fiber The reflected Fiber object.
154 */
155 public function getFiber(): Fiber {}
156
157 /**
158 * @return string Current file of fiber execution.
159 *
160 * @throws Error If the fiber has not been started or has terminated.
161 */
162 public function getExecutingFile(): string {}
163
164 /**
165 * @return int Current line of fiber execution.
166 *
167 * @throws Error If the fiber has not been started or has terminated.
168 */
169 public function getExecutingLine(): int {}
170
171 /**
172 * @param int $options Same flags as {@see debug_backtrace()}.
173 *
174 * @return array Fiber backtrace, similar to {@see debug_backtrace()}
175 * and {@see ReflectionGenerator::getTrace()}.
176 *
177 * @throws Error If the fiber has not been started or has terminated.
178 */
179 public function getTrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT): array {}
180
181 /**
182 * @return callable Callable used to create the fiber.
183 *
184 * @throws Error If the fiber has been terminated.
185 */
186 public function getCallable(): callable {}
187}
188```
189
190#### Unfinished Fibers
191
192Fibers 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.
193
194#### Fiber Stacks
195
196Each 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.
197
198## PHP 8.1+
199
200This 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.
201
