[doc-en] master: pcntl_async_signals(): document when signal handlers are called (#6066)
| From: | Asish Kumar via GitHub | 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>