$ show amphp/amp
amphp/amp is a PHP library providing fundamental asynchronous concurrency primitives: Futures (promises) and Cancellations. It is built on top of the Revolt event loop and leverages PHP 8.1 fibers for cooperative multitasking, eliminating the need for generator-based coroutines or callback-heavy APIs. The library offers a Future class with methods like map(), catch(), finally(), and await() for composing asynchronous operations, along with combinators (await, awaitFirst, awaitAny, awaitAnyN, awaitAll) for concurrent execution. Cancellation is handled via a clean interface with implementations for timeouts (TimeoutCancellation), OS signals (SignalCancellation), manual cancellation (DeferredCancellation), and composition (CompositeCancellation). Utility functions include async() for spawning fibers, delay() for non-blocking sleep, trapSignal() for awaiting signals, and weakClosure() to prevent circular references in closures. The architecture is modular, with internal state management separated from public APIs, and strict typing throughout. External dependency is limited to revolt/event-loop for the event loop and suspension API.
The LLM identified 5 files worth highlighting for reuse:
Core Future class representing the eventual result of an asynchronous operation. Provides map(), catch(), finally(), await(), and iterate() methods. Internally uses FutureState to manage callbacks and state transitions. Demonstrates clean separation of concerns, proper error handling, and integration with fibers via EventLoop::getSuspension(). The iterate() method enables concurrent iteration over futures in completion order, handling both arrays and generators with weak references to avoid memory leaks.
Simple deferred pattern for creating and completing a Future. Encapsulates FutureState and provides complete() and error() methods. The getFuture() method returns the associated Future. Uses ForbidCloning and ForbidSerialization traits to prevent misuse. This is a clean, self-contained implementation of the deferred/promise pattern.
Cancellation implementation that automatically triggers after a specified timeout. Uses EventLoop::delay() to schedule cancellation. Includes debug backtrace information in the exception message when assertions are enabled, aiding debugging. Properly cleans up the event loop watcher on destruction. Demonstrates integration of cancellation with event loop timers.
Combines multiple Cancellation instances into one. Cancels when any of the constituent cancellations is requested. Manages subscriptions and unsubscriptions carefully to avoid memory leaks. Uses a closure that captures references to the exception and callbacks to ensure proper cleanup. Demonstrates advanced composition pattern with asynchronous event handling.
Contains the weakClosure() function which creates a closure that maintains a weak reference to the bound object, preventing circular references that would delay garbage collection. Uses WeakReference, reflection, and closure rebinding. Also includes async(), delay(), trapSignal(), and now() functions. The weakClosure implementation is particularly notable for its handling of different closure types (anonymous, first-class callable, __invoke) and its use of WeakReference.