API Reference

API Reference

The complete public surface of FiberLoops. Three types, one of them an interface and one an exception.

namespace InitPHP\FiberLoops;

final class Loop implements LoopInterface

Loop is the scheduler. Construct it with no arguments — tasks are added only through defer() and await():

use InitPHP\FiberLoops\Loop;

$loop = new Loop();

• defer()
• run()
• next()
• sleep()
• await()
• Exceptions
• LoopInterface

---

defer()

public function defer(callable|Fiber $task): void

Queue a task to be run by run().

Parameters	$task — a callable (wrapped in a new Fiber) or a Fiber (queued as-is). A callable is invoked with no arguments.
Returns	void
Notes	Safe to call during run(); a task deferred mid-run is picked up on the next pass.

$loop->defer(function () {
    echo "queued work\n";
});

See Deferring & Running Tasks.

---

run()

public function run(): void

Run every queued task to completion. Blocks until the queue is empty, advancing each task one step per pass (start → resume → remove when terminated).

Parameters	none
Returns	void
Notes	An empty loop is a no-op. A task that never returns blocks forever. An uncaught exception inside a task propagates out of run().

$loop->run();

See Core Concepts → How run() advances tasks.

---

next()

public function next(mixed $value = null): mixed

Cooperatively yield from the current task back to the scheduler. The task resumes on the next pass, just after this call.

Parameters	$value — value yielded to the driver. Ignored by the bundled scheduler.
Returns	mixed — the value the driver resumes with; null under run() / await().
Throws	LoopException if called outside a fiber.

$loop->defer(function () use ($loop) {
    echo "before\n";
    $loop->next();
    echo "after\n";
});

See Yielding & Sleeping → next().

---

sleep()

public function sleep(int|float $seconds): void

Cooperatively pause the current task for at least $seconds, while sibling tasks keep running.

Parameters	$seconds — duration. Non-positive returns immediately without yielding.
Returns	void
Throws	LoopException if called outside a fiber (except sleep(0), which never yields).
Notes	A busy-wait that yields via next() on each iteration — the CPU stays busy; the loop never idles.

$loop->defer(function () use ($loop) {
    $loop->sleep(0.2);
    echo "woke up\n";
});

See Yielding & Sleeping → sleep().

---

await()

public function await(callable|Fiber $task): mixed

Run a task to completion and return its value.

Parameters	$task — a callable (wrapped in a new Fiber) or a Fiber, started or not.
Returns	mixed — the task's return value, or null if it returns none.
Behaviour	From the main context, drives the task synchronously. From inside a task, yields between the task's steps so siblings keep running.

$result = $loop->await(function () use ($loop) {
    $loop->next();
    return 42;
});
// $result === 42

See Awaiting Results.

---

Exceptions

namespace InitPHP\FiberLoops\Exception;

class LoopException extends \RuntimeException

Thrown when the loop is driven in a way its cooperative model does not allow — most commonly, calling next() or sleep() from outside a fiber. It wraps what would otherwise be a bare FiberError in a package-namespaced type with an actionable message. Catch it as LoopException, RuntimeException, or Throwable.

use InitPHP\FiberLoops\Exception\LoopException;

try {
    $loop->next();          // from the main script
} catch (LoopException $e) {
    echo $e->getMessage();
    // Loop::next() must be called from within a fiber, e.g. inside a task
    // passed to Loop::defer() or Loop::await().
}

See Error Handling.

---

LoopInterface

namespace InitPHP\FiberLoops;

interface LoopInterface
{
    public function defer(callable|Fiber $task): void;
    public function run(): void;
    public function next(mixed $value = null): mixed;
    public function sleep(int|float $seconds): void;
    public function await(callable|Fiber $task): mixed;
}

Loop implements this contract. Depend on LoopInterface (not the concrete Loop) when you want to swap scheduling strategies or substitute a test double — see Testing → Depend on LoopInterface.