diff --git a/README.md b/README.md index abbbc0dc..150dea60 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,9 @@ $suspension->suspend(); print '++ Script end' . PHP_EOL; ``` -Callbacks registered on the Revolt event-loop are automatically run as coroutines and it's safe to suspend them. Apart from the event-loop API, `Amp\async()` can be used to start an independent call stack. +Callbacks registered on the Revolt event-loop are automatically run as coroutines. It is safe to suspend within those +callbacks. Apart from the event-loop API, `Amp\async()` can be used to start a coroutine (that is, a new fiber or an +independent call stack). ```php $signals */ +function trapSignal(int|array $signals, bool $reference = true, ?Cancellation $cancellation = null): int +``` + +`trapSignal` suspends the current coroutine (fiber) until one of the given signals is received by the process or, if +provided, the cancellation is cancelled. Optionally, the underlying event-loop callback may be unreferenced, allowing +the event-loop to exit if no other referenced events are active. The signal number of the received signal is returned. + +```php +now(): float +``` + +`now` returns a high-resolution time relative to an arbitrary point in time. This function may be used to calculate +time differences independent of wall-time. + +```php +/** + * @template TReturn + * @param Closure(...):TReturn $closure + * @return Closure(...):TReturn + */ +function weakClosure(\Closure $closure): \Closure +``` + +`weakClosure` wraps a given closure, returning a new `Closure` instance which maintains a weak-reference to any +`$this` object held by the closure (a weak-closure). This allows a class instance to hold a self-referencing closure +without creating a circular-reference that would prevent or delay automatic garbage collection. Invoking the returned +`Closure` after the object is destroyed will throw an instance of `Error`. + +#### Interval + +An `Interval` registers a callback in the event-loop which is invoked within a new coroutine every given number of +seconds until either the `Interval::disable()` method is called or the object is destroyed. If an `Interval` is +disabled, it can be re-enabled using `Interval::enable()`. + +Holding an instance of `Interval` within an instance of another class is a convenient way to run a repeating timer +during the existence of that object. When the holding object is destroyed, the instance of `Interval` will also be +destroyed, cancelling the repeating timer in the event-loop. Use `weakClosure()` to avoid having a circular reference +to the holding object, which will delay garbage collection of the holding object. + +```php +// Creates a callback which is invoked every 0.5s +// unless disabled or the object is destroyed. +$interval = new Interval(0.5, function (): void { + // ... +}); + +// Disable the repeating timer, stopping future +// invocations until enabled again. +$interval->disable(); + +// Enable the repeating timer. The callback will +// not be invoked until the given timeout has elapsed. +$interval->enable(); +``` + ## Versioning `amphp/amp` follows the [semver](http://semver.org/) semantic versioning specification like all other `amphp` packages.