signal

(PHP 8.6+, True Async 1.0)

signal() — Espera una señal del SO. Devuelve un Future que se resuelve con un valor Signal cuando se recibe la señal.

Descripción

signal(Async\Signal $signal, ?Async\Completable $cancellation = null): Async\Future

Crea un manejador de señal del SO de un solo uso. Cada llamada a signal() crea un nuevo Future que se resuelve al recibir la primera señal especificada. Si se proporciona el parámetro $cancellation, el Future será rechazado cuando la cancelación se active (p. ej., al expirar el timeout).

Múltiples llamadas a signal() con la misma señal funcionan independientemente — cada una recibirá una notificación.

Parámetros

signal Un valor del enum Async\Signal que especifica la señal esperada. Por ejemplo: Signal::SIGINT, Signal::SIGTERM, Signal::SIGUSR1.

cancellation Un objeto opcional que implementa Async\Completable (p. ej., un resultado de llamar a timeout()). Si el objeto de cancelación se activa antes de que llegue la señal, el Future será rechazado con la excepción correspondiente (p. ej., Async\TimeoutException).

Si el objeto de cancelación ya se ha completado al momento de la llamada, signal() devuelve inmediatamente un Future rechazado.

Valores de retorno

Devuelve Async\Future<Async\Signal>. Cuando se recibe la señal, el Future se resuelve con el valor del enum Async\Signal correspondiente a la señal recibida.

Errores/Excepciones

• Async\OperationCanceledException — si se activa el token de cancelación (incluido el timeout). La excepción original del token está disponible a través de $e->getPrevious() (por ejemplo, TimeoutException al usar timeout()).

Ejemplos

Ejemplo #1 Esperar una señal con timeout

<?php
use Async\Signal;
use function Async\signal;
use function Async\timeout;
use function Async\await;

try {
    $result = await(signal(Signal::SIGINT, timeout(5000)));
    echo "Señal recibida: " . $result->name . "\n";
} catch (Async\OperationCanceledException $e) {
    echo "Señal no recibida en 5 segundos\n";
}
?>

Ejemplo #2 Recibir una señal desde otra corrutina

<?php
use Async\Signal;
use function Async\signal;
use function Async\await;
use function Async\spawn;

$future = signal(Signal::SIGUSR1);

spawn(function() {
    posix_kill(getmypid(), SIGUSR1);
});

$result = await($future);
echo "Señal recibida: " . $result->name . "\n";
var_dump($result === Signal::SIGUSR1); // bool(true)
?>

Ejemplo #3 Apagado ordenado con SIGTERM

<?php
use Async\Signal;
use function Async\signal;
use function Async\await;
use function Async\spawn;
use function Async\graceful_shutdown;

spawn(function() {
    await(signal(Signal::SIGTERM));
    echo "SIGTERM recibido, apagando...\n";
    graceful_shutdown();
});
?>

Ejemplo #4 Timeout ya expirado

<?php
use Async\Signal;
use function Async\signal;
use function Async\timeout;
use function Async\await;
use function Async\delay;

$t = timeout(1);
delay(50); // El timeout ya expiró

$future = signal(Signal::SIGINT, $t);

try {
    await($future);
} catch (Async\OperationCanceledException $e) {
    echo get_class($e) . "\n"; // Async\OperationCanceledException
    echo get_class($e->getPrevious()) . "\n"; // Async\TimeoutException
}
?>

Notas

Nota: Cada llamada a signal() crea un manejador de un solo uso. Para esperar la misma señal nuevamente, llame a signal() de nuevo.

Nota: Signal::SIGINT y Signal::SIGBREAK funcionan en todas las plataformas, incluyendo Windows. Las señales SIGUSR1, SIGUSR2 y otras señales POSIX solo están disponibles en sistemas Unix.

Nota: Signal::SIGKILL y Signal::SIGSEGV no pueden ser capturadas — esta es una limitación del sistema operativo.

Signal

El enum Async\Signal define las señales del SO disponibles:

Ver también

• timeout() — crear un timeout para limitar la espera
• await() — esperar el resultado de un Future
• graceful_shutdown() — apagado ordenado del planificador
• Cancelación — mecanismo de cancelación