Add Async\watch_filesystem() — filesystem watcher returning Future

[EdmondDantes]

Summary

Add Async\watch_filesystem() function that watches a file or directory for changes and returns a Future<FileSystemEvent> that resolves on the first detected change.

PHP API

namespace Async;

enum FileSystemEventType: int {
    case Rename = 1;  // UV_RENAME
    case Change = 2;  // UV_CHANGE
}

final readonly class FileSystemEvent {
    public readonly string $path;
    public readonly ?string $filename;
    public readonly int $events;  // bitmask
}

function watch_filesystem(
    string $path,
    bool $recursive = false,
    ?Completable $cancellation = null
): Future {}

Implementation

The low-level zend_async_filesystem_event_t infrastructure already exists in the API and libuv reactor. This task adds the PHP-level function that bridges it to a Future using the pattern from TaskGroup::race().

Files to modify

• async.stub.php — stub definitions
• async_arginfo.h — regenerated arginfo
• async.c — function implementation and class registration
• async.h — extern declarations