Scope: Управління часом життя корутин ​

function processUser($userId) {
    spawn(sendEmail(...), $userId);
    spawn(updateCache(...), $userId);
    spawn(logActivity(...), $userId);

    return "OK";
}

processUser(123);
// Функція повернулася, але три корутини все ще працюють!
// Хто за ними стежить? Коли вони завершаться?
// Хто обробить виключення, якщо вони виникнуть?

function processUser($userId):string {
    spawn(sendEmail(...), $userId);
    spawn(updateCache(...), $userId);
    spawn(logActivity(...), $userId);

    // Чекаємо, поки всі корутини в scope завершаться
    $scope->awaitCompletion(Async\timeout(1000));

    return "OK";
}

$scope = new Async\Scope();
$scope->spawn(processUser(...), 123);
$scope->awaitCompletion(Async\timeout(5000));

// Тепер функція поверне результат тільки коли ВСІ корутини завершаться

class UserService
{
    // Тільки один унікальний об'єкт буде володіти унікальним Scope
    // Корутини живуть стільки, скільки живе об'єкт UserService
    private Scope $scope;

    public function __construct() {
        // Створюємо купол для всіх корутин сервісу
        $this->scope = new Async\Scope();
    }

    public function sendNotification($userId) {
        // Запускаємо корутину всередині нашого купола
        $this->scope->spawn(function() use ($userId) {
            // Ця корутина прив'язана до UserService
            sendEmail($userId);
        });
    }

    public function __destruct() {
        // Коли об'єкт видаляється, ресурси гарантовано очищуються
        // Всі корутини всередині автоматично скасовуються
        $this->scope->dispose();
    }
}

$service = new UserService();
$service->sendNotification(123);
$service->sendNotification(456);

// Видаляємо сервіс -- всі його корутини автоматично скасовуються
unset($service);

$mainScope = new Async\Scope();

$mainScope->spawn(function() {
    echo "Main task\n";

    // Створюємо дочірній scope
    $childScope = Async\Scope::inherit();

    $childScope->spawn(function() {
        echo "Subtask 1\n";
    });

    $childScope->spawn(function() {
        echo "Subtask 2\n";
    });

    // Чекаємо завершення підзадач
    $childScope->awaitCompletion(Async\timeout(5000));

    echo "All subtasks done\n";
});

$mainScope->awaitCompletion(Async\timeout(5000));

$scope = new Async\Scope();

$scope->spawn(function() {
    try {
        while (true) {
            echo "Working...\n";
            Async\delay(1000);
        }
    } catch (Async\AsyncCancellation $e) {
        echo "I was cancelled!\n";
    }
});

$scope->spawn(function() {
    try {
        while (true) {
            echo "Also working...\n";
            Async\delay(1000);
        }
    } catch (Async\AsyncCancellation $e) {
        echo "Me too!\n";
    }
});

// Працює 3 секунди
Async\delay(3000);

// Скасовуємо ВСІ корутини в scope
$scope->cancel();

// Обидві корутини отримають AsyncCancellation

$scope = new Async\Scope();

// Встановлюємо обробник помилок
$scope->setExceptionHandler(function (Async\Scope $scope, Async\Coroutine $coroutine, Throwable $e) {
    echo "Error in scope: " . $e->getMessage() . "\n";
    // Можна залогувати, відправити в Sentry тощо.
});

$scope->spawn(function() {
    throw new Exception("Something broke!");
});

$scope->spawn(function() {
    echo "I'm working fine\n";
});

$scope->awaitCompletion(Async\timeout(5000));

// Виведе:
// Error in scope: Something broke!
// I'm working fine

$scope = new Async\Scope();

$scope->spawn(function() {
    try {
        echo "Starting work\n";
        Async\delay(10000); // Довга операція
        echo "Finished\n"; // Не виконається
    } finally {
        // Це ГАРАНТОВАНО виконається
        echo "Cleaning up resources\n";
        closeConnection();
    }
});

Async\delay(1000);
$scope->cancel(); // Скасовуємо через одну секунду

// Виведе:
// Starting work
// Cleaning up resources

$group = new Async\TaskGroup(concurrency: 5);

$group->spawn(fn() => fetchUser(1));
$group->spawn(fn() => fetchUser(2));
$group->spawn(fn() => fetchUser(3));

// Отримати всі результати (чекає завершення всіх завдань)
$results = await($group->all());

// Або отримати перший завершений результат
$first = await($group->race());

// Або перший успішний (ігноруючи помилки)
$any = await($group->any());

$group = new Async\TaskGroup();

$group->spawnWithKey('user', fn() => fetchUser(1));
$group->spawnWithKey('orders', fn() => fetchOrders(1));

// Ітеруємо результати в міру їх готовності
foreach ($group as $key => [$result, $error]) {
    if ($error) {
        echo "Task $key failed: {$error->getMessage()}\n";
    } else {
        echo "Task $key: $result\n";
    }
}

// На верхньому рівні: корутина потрапляє в глобальний scope
spawn(function() {
    echo "I'm in global scope\n";
});

// Всередині корутини: корутина потрапляє в scope викликача
$scope = new Async\Scope();
$scope->spawn(function() {
    spawn(function() {
        echo "I'm in \$scope, same as my parent\n";
    });
});

class HttpClient {
    private Scope $scope;

    public function __construct() {
        $this->scope = new Async\Scope();
    }

    public function get(string $url): Async\Awaitable {
        return $this->scope->spawn(function() use ($url) {
            $ch = curl_init($url);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            try {
                return curl_exec($ch);
            } finally {
                curl_close($ch);
            }
        });
    }

    public function cancelAll(): void {
        // Скасувати всі активні запити
        $this->scope->cancel();
    }

    public function __destruct() {
        // Коли клієнт знищується, всі запити автоматично скасовуються
        $this->scope->dispose();
    }
}

$client = new HttpClient();

$req1 = $client->get('https://api1.com/data');
$req2 = $client->get('https://api2.com/data');
$req3 = $client->get('https://api3.com/data');

// Скасувати всі запити
$client->cancelAll();

// Або просто знищити клієнт -- той самий ефект
unset($client);

$scope = new Async\Scope();
$scope->spawn(function() { /* задача 1 */ });
$scope->spawn(function() { /* задача 2 */ });

// Управління не повернеться, поки обидві задачі не завершаться
$scope->awaitCompletion(Async\timeout(5000));

$scope->cancel();
// Всі корутини в $scope отримають сигнал скасування.
// Дочірні Scope також будуть скасовані -- рекурсивно, на будь-яку глибину.

$scope->dispose();
// Scope закрито. Всі корутини скасовані.
// Нові корутини не можуть бути додані до цього Scope.

$scope->disposeSafely();
// Scope закрито. Корутини продовжують працювати як zombie.
// Scope відстежує їх, але не враховує як активні.