[doc-en] master: pcntl_async_signals(): document when signal handlers are called (#6066)

From: Date: Thu, 12 Nov 2026 15:29:40 +0000
Subject: [doc-en] master: pcntl_async_signals(): document when signal handlers are called (#6066)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23946@lists.php.net to get a copy of this message
Author: Asish Kumar (officialasishkumar) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-11-12T16:29:37+01:00 Commit: https://github.com/php/doc-en/commit/3e4d4fa6a24d0f04db6fa1f42905653bdd853905 Raw diff: https://github.com/php/doc-en/commit/3e4d4fa6a24d0f04db6fa1f42905653bdd853905.diff pcntl_async_signals(): document when signal handlers are called (#6066) * pcntl_async_signals(): document when signal handlers are called With asynchronous signals enabled, the pcntl signal handler only records the signal and sets EG(vm_interrupt); the PHP handler runs the next time the VM checks for interrupts, after a function call returns or on a loop jump. A long-running internal function such as curl_exec() therefore holds the handler back until it returns, unless it calls back into PHP code, as a CURLOPT_XFERINFOFUNCTION callback does. None of this was on the page, which made the delay look like a bug. Add a Notes section describing this, including that a blocking system call such as the one sleep() makes can still be interrupted, and an example that keeps a SIGALRM heartbeat running during a cURL transfer through a progress callback. Checked against ext/pcntl/pcntl.c and Zend/zend_vm_def.h, and by running the example on PHP 8.4 against a local server that answers after three seconds: the handler runs every second with the callback, and only once after curl_exec() returns without it. Fixes #1712 * pcntl_async_signals(): apply review suggestions Changed paths: M reference/pcntl/functions/pcntl-async-signals.xml Diff: diff --git a/reference/pcntl/functions/pcntl-async-signals.xml b/reference/pcntl/functions/pcntl-async-signals.xml index be39e553ed00..8112e54db3b3 100644 --- a/reference/pcntl/functions/pcntl-async-signals.xml +++ b/reference/pcntl/functions/pcntl-async-signals.xml @@ -66,6 +66,67 @@ </informaltable> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title>Calling signal handlers during a cURL transfer</title> + <simpara> + Without the progress callback, the handler would not be called until the + transfer has completed. <constant>CURLOPT_XFERINFOFUNCTION</constant> is + available as of PHP 8.2.0; use <constant>CURLOPT_PROGRESSFUNCTION</constant> + on earlier versions. + </simpara> + <programlisting role="php"> +<![CDATA[ +<?php +pcntl_async_signals(true); + +pcntl_signal(SIGALRM, function () { + echo "Heartbeat\n"; + pcntl_alarm(1); +}); +pcntl_alarm(1); + +$ch = curl_init('https://example.com/slow-endpoint'); +curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); + +// Calling back into PHP code during the transfer lets the handler run +curl_setopt($ch, CURLOPT_NOPROGRESS, false); +curl_setopt($ch, CURLOPT_XFERINFOFUNCTION, function () { + return 0; +}); + +$response = curl_exec($ch); +?> +]]> + </programlisting> + </example> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <simpara> + With asynchronous signal handling enabled, a handler installed with + <function>pcntl_signal</function> is not called at the moment the signal + is received. The signal is recorded, and the handler is called the next + time the engine checks for pending signals while executing PHP code, for + instance after a function call returns, or on the next iteration of a loop. + </simpara> + <simpara> + As a consequence, a long-running call to an internal function, such as + <function>curl_exec</function> or a database query, is not interrupted to + call the handler: the handler is only called once that function returns. + The handler is called earlier only if the function calls back into PHP code + while it runs, for instance through a + <constant>CURLOPT_XFERINFOFUNCTION</constant> callback. + </simpara> + <simpara> + A signal may still interrupt a system call the function is blocked in. + For instance, <function>sleep</function> then returns early, and the + handler is called once it has returned. + </simpara> + </refsect1> + <refsect1 role="seealso"><!-- {{{ --> &reftitle.seealso; <simplelist>

« previous php.doc.cvs (#23946) next »