Skip to content

Fix GH-25541, GH-25548, GH-25549: forward signals from threads without PHP context - #25542

Open
phcorp wants to merge 11 commits into
php:PHP-8.4from
phcorp:fix-gh25541
Open

phcorp wants to merge 11 commits into
php:PHP-8.4from
phcorp:fix-gh25541

Conversation

@phcorp

@phcorp phcorp commented Nov 17, 2026 •

Copy link
Copy Markdown

Fixes GH-25541.
Fixes GH-25548.
Fixes GH-25549.

Summary

Under ZTS, a signal sent to the process can be delivered to any thread that does not block it, including a thread that never ran PHP. Such a thread has no TSRM storage, so PHP's signal handlers cannot do their work there. Depending on the build, PHP crashes, is killed by the signal, or loses it.

This PR defines what happens to those signals. A small new component, Zend/zend_signal_forward.c, forwards each one to the PHP thread that owns it. The signal handler only sets a flag and writes one byte to a pipe, and a helper thread calls pthread_kill() from normal context.

Affects ZTS builds on POSIX systems, with zend signals on or off
No change for NTS builds and Windows
Main code Zend/zend_signal_forward.c and .h
PCNTL-specific code ext/pcntl/pcntl.c only registers handlers and calls the component
New cost One helper thread and one pipe, from the first pcntl handler or running execution timer until shutdown

The problem

flowchart TD
    K["kill() or alarm() targets the process"] --> T{"Which thread does<br/>the kernel pick?"}
    T -->|"A PHP thread"| OK["Handler runs normally"]
    T -->|"A thread that never ran PHP,<br/>such as a libdispatch worker"| B{"Build?"}
    B -->|"--disable-zend-signals"| C["pcntl_signal_handler() reads PCNTL_G()<br/>through a NULL TSRM pointer: crash"]
    B -->|"Zend signals (default)"| D["zend_signal_handler() uses the original<br/>disposition: SIG_DFL ends the process"]
Loading

This is more likely than it sounds. pcntl_signal_dispatch() blocks signals on the PHP thread while handlers run, so a signal arriving at that moment has to go to another thread.

Behaviour before and after

Each row was measured on debug ZTS builds on macOS arm64.

Scenario Zend signals, before No zend signals, before After, both builds
Signal with a pcntl handler lands on a non-PHP thread Process killed Crash Handler runs
Execution timeout lands on a non-PHP thread Process killed Process killed Timeout error
Timeout of one thread lands on a PHP thread with no time limit That thread's request dies That thread's request dies The thread that armed the timer times out
Signal lands on a PHP thread with no handler, while another thread has one Process killed Signal lost Other thread's handler runs
Two threads handle a signal and the most recent one finishes Process killed Process killed Remaining thread's handler runs
PHP restarts in the same process, then a signal lands on a non-PHP thread Crash Crash Handler runs
Fault on a non-PHP thread with a handler for it Process killed Hang Process killed by the fault

Signal policy

Thread that receives the signal What happens
PHP thread with a handler for the signal The handler runs, as before
PHP thread without one, or a thread with no TSRM context Forwarded to the owner
No owner The signal takes its current action
Any thread, for SIGSEGV, SIGBUS, SIGFPE, SIGILL or SIGTRAP Stays on the faulting thread and takes the default action
Non-PHP thread, for a signal with a handler from before PHP started (zend signals) That handler runs, as before
Non-PHP thread, for the signal of a timer disarmed in the last 2 seconds Dropped

The owner of a signal is the thread that most recently registered a handler for it. If no thread has a handler, it is the thread that most recently armed the execution timer delivering that signal.

Design

flowchart LR
    subgraph H["Signal handler: any thread"]
        F["zend_signal_forward()"]
    end
    subgraph S["Shared state"]
        P[("pending[signo]<br/>atomic")]
        W[("pipe")]
        O[("thread records<br/>protected by mutex")]
    end
    subgraph N["Normal context"]
        HT["Helper thread"]
        R["PHP threads:<br/>acquire, release, timers"]
    end
    T["PHP thread that<br/>owns the signal"]

    F -->|"1. set flag"| P
    F -->|"2. write one byte"| W
    W -->|"3. wakes"| HT
    HT -->|"4. takes flag"| P
    HT -->|"5. chooses owner"| O
    HT -->|"6. pthread_kill()"| T
    R -->|"update under mutex"| O
Loading

Why a helper thread

POSIX lists pthread_kill() as async-signal-safe, so calling it directly from the handler was the first approach. On macOS it takes a libpthread lock. If the signal interrupts a thread that already holds that lock, the process aborts:

BUG IN CLIENT OF LIBPLATFORM: Trying to recursively lock an os_unfair_lock

A stress test that creates threads while forwarding signals aborted in 8 of 8 runs.

How a signal is forwarded

sequenceDiagram
    autonumber
    participant K as Kernel
    participant F as Non-PHP thread
    participant H as Helper thread
    participant O as Owner PHP thread

    K->>F: Deliver SIGUSR1
    F->>F: Owner exists and pid matches?
    F->>F: pending[SIGUSR1] = timer generation
    F->>H: write() one byte to the pipe
    F-->>K: Handler returns
    H->>H: read() wakes, lock mutex
    H->>H: Take pending[SIGUSR1], choose owner
    H->>O: pthread_kill(owner, SIGUSR1)
    H->>H: Unlock mutex
    O->>O: Normal PHP handler path runs
Loading

What each signal handler decides

flowchart TD
    A["Signal delivered"] --> B{"Thread runs PHP?"}
    B -->|"Yes"| D{"This thread has<br/>a handler?"}
    D -->|"Yes"| E["Run the handler as usual"]
    D -->|"No"| C
    B -->|"No"| C{"Fault signal?"}
    C -->|"Yes"| G["Default action,<br/>stays on this thread"]
    C -->|"No"| I{"Handler installed<br/>before PHP started?"}
    I -->|"Yes, with zend signals"| J["Call that handler"]
    I -->|"No"| L{"An owner exists?"}
    L -->|"Yes"| M["Forwarded"]
    L -->|"No"| N{"Ignored by a PHP thread,<br/>or timer just disarmed?"}
    N -->|"Yes"| Q["Dropped"]
    N -->|"No"| R["Current action"]
Loading

Audit of the handler path

On a thread with no TSRM context, the path only uses:

Call Async-signal-safe
zend_atomic_* Yes, when lock-free. Forwarding is compiled out with HAVE_NO_ATOMICS
getpid(), time(), write(), kill(), signal(), sigaction(), sigemptyset(), sigaddset() Yes, listed by POSIX
pthread_sigmask() Yes, listed by POSIX
pthread_getspecific(), through tsrm_is_managed_thread() Not listed. See below

pthread_getspecific() is the one assumption. It is needed to tell whether the thread has TSRM context. On glibc, musl, macOS and FreeBSD it is a lock-free read of the current thread's slot. __thread is worse here: its first access in a shared library allocated memory on macOS in 200 of 200 runs.

This PR also removes raise(), fprintf() and writes to SIGG() from paths that a thread with no TSRM context can reach.

Thread lifetime

The helper holds the mutex while it calls pthread_kill(), and a thread needs the same mutex to remove its record. A thread therefore cannot finish exiting while a signal is being sent to it, so a signal never targets an exited thread or a recycled identifier.

sequenceDiagram
    participant H as Helper thread
    participant M as Mutex
    participant O as Owner thread

    H->>M: Lock
    H->>O: pthread_kill(owner, signo)
    O->>M: Wants to remove its record, waits
    H->>M: Unlock
    M->>O: Lock acquired
    O->>O: Remove record
    O->>M: Unlock
    O->>O: Exit
    Note over H,O: The helper can no longer find this thread
Loading

A thread-specific key removes the record of a thread that exits without shutting down a request.

Ownership

stateDiagram-v2
    [*] --> NoOwner
    NoOwner --> Owned: pcntl_signal() or a timer is armed
    Owned --> Owned: Another thread registers, or the owner leaves and a successor takes over
    Owned --> NoOwner: The last registered thread leaves
    NoOwner --> [*]: Shutdown
Loading
Function Called by Purpose
zend_signal_forward() Signal handlers Hands a signal to its owner
zend_signal_forward_or_default() pcntl_signal_handler() The same, taking the default action without an owner
zend_signal_forward_acquire() pcntl_signal() Registers a handler
zend_signal_forward_release() pcntl_signal(), zend_sigaction(), pcntl RSHUTDOWN Removes a handler and sets the disposition the remaining threads need
zend_signal_forward_has_handler() zend_set_timeout_ex() Keeps the timer from replacing another thread's handler
zend_signal_forward_timer_arm(), _timer_disarm() zend_set_timeout_ex(), zend_unset_timeout() Tracks the running timer
zend_signal_forward_request_shutdown() php_request_shutdown() Clears the thread's registrations
zend_signal_forward_fork_child() pcntl_fork(), pcntl_rfork(), pcntl_forkx() Restores forwarding in the child

A signal's disposition is process-wide. When a handler is released, the component keeps it for the remaining handlers, restores an armed timer's handler, or applies a SIG_IGN that another thread asked for.

Fork

flowchart TD
    A["fork()"] --> B["Child: only the forking thread exists"]
    B --> C{"Called through<br/>pcntl_fork()?"}
    C -->|"Yes"| D["zend_signal_forward_fork_child()"]
    C -->|"No"| E["Handlers see a different pid<br/>and do not forward"]
    E --> F["Next registration in the child"]
    D --> G["New mutex and pipe,<br/>keep only this thread's record,<br/>restart the helper if needed"]
    F --> G
Loading

There are deliberately no pthread_atfork() handlers. Holding a lock across fork() deadlocked against a thread interrupted inside malloc().

Signal semantics

siginfo of a forwarded signal

A forwarded signal is a new signal sent by pthread_kill(), so its siginfo no longer describes the original sender:

Field Direct delivery Forwarded delivery
si_signo The signal Unchanged
si_pid, si_uid The original sender Not the original sender
si_code How the signal was sent The platform's code for a thread-directed signal
si_value, SIGCHLD status and times The original values Lost

Handlers should not use these fields for authentication or routing. For SIGCHLD, loop on pcntl_waitpid(-1, $status, WNOHANG).

Repeated, blocked and pending signals

  • Repeated signals coalesce. This includes real-time signals when they are forwarded.
  • A signal blocked by the owner stays pending on the owner, with no failover while that thread is alive. If the owner exits, the signal is sent to the process again.
  • A pending signal when a handler is replaced runs the handler in place at delivery.
  • A signal forwarded just as the owner leaves is delivered before the handler is removed. If the owner has already left, the signal takes its current action.

Limitations

  • The helper thread stays until shutdown, so unshare(CLONE_NEWUSER) fails once it exists.
  • Handlers installed directly with zend_signal() or zend_sigaction() are not forwarded, as before.
  • Signals from NSIG up, such as real-time signals on FreeBSD, are not forwarded.
  • Two threads with time limits still share one process-wide timer, as before. On builds with ZEND_MAX_EXECUTION_TIMERS, each thread has its own timer and this code is not used.
  • A signal arriving within 2 seconds of a timer being disarmed is treated as that timer's signal.

Review guide

The early commits show how the fix evolved, and the last commit moves the result into its own component. Reviewing the full diff against the base branch is much easier than going commit by commit.

# File What to look at
1 Zend/zend_signal_forward.h The API
2 Zend/zend_signal_forward.c Handler path, helper thread, ownership, lifecycle
3 Zend/zend_signal.c zend_signal_handler_defer(), zend_signal_handler(), zend_sigaction(), zend_signal_init()
4 ext/pcntl/pcntl.c pcntl_signal(), pcntl_signal_handler(), RSHUTDOWN
5 Zend/zend_execute_API.c zend_timeout_handler(), zend_set_timeout_ex(), zend_unset_timeout()
6 ext/zend_test/test.c The test helper zend_test_signal_forwarding()

Questions where review would help most:

  • Is one helper thread per ZTS process acceptable for a stable branch, or should this target master?
  • Is the 2-second window for the signal of a disarmed timer acceptable?

Testing

Test Covers
ext/zend_test/tests/signal_forwarding.phpt Delivery from a foreign thread, owner handover, owner exit, a thread with no handler, concurrent registration, timers, repeated signals, handler replacement, exit with a pending signal, thread identifier reuse, fork
ext/pcntl/tests/gh25541.phpt A signal on a non-PHP thread reaches the pcntl handler
ext/pcntl/tests/gh25541_fault.phpt Faults are not forwarded (skipped under sanitizers, which handle faults themselves)
ext/pcntl/tests/gh25541_fork.phpt Forwarding in the child of pcntl_fork()
ext/pcntl/tests/gh25548.phpt The execution timeout on a non-PHP thread
ext/pcntl/tests/gh25548_stale_timer.phpt The signal of a disarmed timer

The timer tests are skipped on builds where the execution timer is not process-wide.

Results on debug ZTS builds on macOS arm64, with zend signals on and off:

  • Each test above passes 20 of 20 independent runs.
  • ThreadSanitizer reports no race, and the tests pass under AddressSanitizer.
  • Stress tests pass: forwarding during thread creation, fork() during malloc(), and concurrent handler registration.
  • ext/pcntl/tests, ext/posix/tests, ext/zend_test/tests, sapi/cli/tests, Zend/tests and tests show no regression. pcntl_qosclass.phpt fails intermittently on a heavily loaded machine, with and without this PR.
  • Builds with --enable-werror pass for ZTS and NTS, with zend signals on and off.
  • A request that registers nothing takes the same number of mutex locks as before.

Multi-threaded requests, handlers installed before PHP starts, restart and forced interleavings cannot be covered by a phpt, so I checked them with an embed SAPI program.

Not covered: I have not run this on Linux locally, so Linux coverage comes from CI. Pull request CI has no macOS ZTS job. No job disabled zend signals, so this PR adds --disable-zend-signals to the nightly variation job.

Targeting PHP-8.4, as the bug is present in every maintained branch.

Under ZTS with --disable-zend-signals, pcntl_signal_handler() is installed
directly with sigaction(). A process-directed signal (kill(), alarm()) may be
delivered to any thread that does not block it, including one with no TSRM
storage, such as the libdispatch workers of every macOS process. PCNTL_G()
then dereferences NULL.

Mirror zend_signal_handler_defer(): when the thread is not managed by TSRM,
leave the pcntl globals alone and forward the signal with pthread_kill() to
the thread that last installed a handler.
Comment thread ext/pcntl/pcntl.c
#endif
ZEND_GET_MODULE(pcntl)
#endif

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

diff --git a/Zend/zend_signal.c b/Zend/zend_signal.c
index 83f8aa0852d..d4df3cbcd0a 100644
--- a/Zend/zend_signal.c
+++ b/Zend/zend_signal.c
@@ -79,6 +79,11 @@ static const int zend_sigs[] = { TIMEOUT_SIG, SIGHUP, SIGINT, SIGQUIT, SIGTERM,
 static zend_signal_entry_t global_orig_handlers[NSIG];
 static sigset_t            global_sigmask;

+#ifdef ZTS
+static pthread_t        global_handler_threads[NSIG];
+static zend_atomic_bool global_handler_thread_set[NSIG];
+#endif
+
 /* {{{ zend_signal_handler_defer
  *  Blocks signals if in critical section */
 static void zend_signal_handler_defer(int signo, siginfo_t *siginfo, void *context)
@@ -91,6 +96,11 @@ static void zend_signal_handler_defer(int signo, siginfo_t *siginfo, void *conte
         * Or it could be delivered to a thread that didn't execute PHP yet.
         * In the latter case we act as if SIGG(active) is false. */
        if (tsrm_is_shutdown() || !tsrm_is_managed_thread()) {
+               if (!tsrm_is_shutdown() && zend_atomic_bool_load(&global_handler_thread_set[signo-1])) {
+                       pthread_kill(global_handler_threads[signo-1], signo);
+                       errno = errno_save;
+                       return;
+               }
                /* Forward to default handler handler */
                zend_signal_handler(signo, siginfo, context);
                return;
@@ -245,6 +255,18 @@ ZEND_API void zend_sigaction(int signo, const struct sigaction *act, struct siga
                        SIGG(handlers)[signo-1].handler = (void *) act->sa_handler;
                }

+#ifdef ZTS
+               if (SIGG(handlers)[signo-1].handler == (void *) SIG_DFL || SIGG(handlers)[signo-1].handler == (void *) SIG_IGN) {
+                       if (zend_atomic_bool_load(&global_handler_thread_set[signo-1])
+                        && pthread_equal(global_handler_threads[signo-1], pthread_self())) {
+                               zend_atomic_bool_store(&global_handler_thread_set[signo-1], false);
+                       }
+               } else {
+                       global_handler_threads[signo-1] = pthread_self();
+                       zend_atomic_bool_store(&global_handler_thread_set[signo-1], true);
+               }
+#endif
+
                memset(&sa, 0, sizeof(sa));
                if (SIGG(handlers)[signo-1].handler == (void *) SIG_IGN) {
                        sa.sa_sigaction = (void *) SIG_IGN;
@@ -357,6 +379,15 @@ void zend_signal_deactivate(void)
         * state that is reset below will not be accessed. */
        *((volatile int *) &SIGG(active)) = 0;

+#ifdef ZTS
+       for (int signo = 1; signo < NSIG; signo++) {
+               if (zend_atomic_bool_load(&global_handler_thread_set[signo-1])
+                && pthread_equal(global_handler_threads[signo-1], pthread_self())) {
+                       zend_atomic_bool_store(&global_handler_thread_set[signo-1], false);
+               }
+       }
+#endif
+
        SIGG(running) = 0;
        SIGG(blocked) = 0;
        SIGG(depth) = 0;

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, you were right. On a default ZTS build, a signal on a foreign thread killed the process even with a pcntl handler. I applied your change, with two additions: faults (SIGSEGV, SIGBUS, SIGFPE, SIGILL) are not forwarded, since the faulting thread would otherwise spin forever, and signals at or above NSIG are not tracked. pcntl now tracks the owner per signal too, and the test runs with zend signals enabled.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update: I replaced this approach after testing it further. Calling pthread_kill() from the signal handler aborts the process on macOS when the interrupted thread holds a libpthread lock, which a stress test hit in 8 of 8 runs. The handler now only sets a flag and writes to a pipe, and a helper thread does the pthread_kill(). The PR description explains the design and its limitations.

On a default ZTS build, a signal delivered to a thread that never ran PHP
reached zend_signal_handler(), which used the original disposition. A signal
with a pcntl handler or the execution timeout therefore ended the process.
Record the thread that installed each handler in zend_sigaction() and forward
the signal to it.

Track the thread per signal in pcntl too. With a single slot, a signal could
be sent to a thread that had no handler for it, and the end of any request
that installed a handler stopped forwarding for the other threads.

Never forward SIGSEGV, SIGBUS, SIGFPE or SIGILL. The faulting instruction
would run again when the handler returned, so the thread would spin forever.

Run the test with zend signals as well, as no CI job disables them.
SIGTRAP can be synchronous too: the trapping instruction runs again when the
handler returns, so the thread would spin forever.

A handler installed before PHP started used to receive the signals delivered
to threads that never ran PHP. Forwarding them to a PHP thread bypassed it,
and could end the request with a bogus execution timeout.
When PHP starts again in the same process, the handler left by the previous
startup was saved as the original one. A signal delivered to a thread that
never ran PHP then made zend_signal_handler_defer() call itself until the
stack overflowed.
The thread and its flag were two separate variables, updated without any
synchronization:
- a thread finishing its request could erase the record of a thread that had
  just installed a handler, so that the signal then took the default action;
- pthread_kill() could be given a thread that had already exited;
- after fork(), the child could forward to a thread that does not exist there.

Keep one table in Zend, used with and without zend signals, protected by a
spinlock that is held across pthread_kill(). A thread forgets its signals
before it exits, which waits for any forward in progress.

The lock holds the pid of its holder, so that a forked child can take over a
lock whose holder does not exist there. pthread_atfork() handlers are avoided
on purpose: holding the lock across fork() deadlocks with a forwarding thread
interrupted while it holds an allocator lock. pcntl_fork() keeps the record of
the forking thread in the child.

Forget a signal before its handler goes away, and record it before the handler
is installed, so that a forwarded signal does not take the default action.

Skip the fault test under sanitizers, which handle faults themselves.
Calling pthread_kill() from a signal handler aborts the process on macOS when
the interrupted thread holds the libpthread lock that it takes, and the spinlock
made the handler wait for other threads.

The handler now only sets an atomic flag and writes to a pipe. A helper thread
calls pthread_kill() in normal context, under a mutex that a thread also takes
to remove its record before it exits. A thread-specific key removes the record
of a thread that exits without shutting down a request.

Each thread that handles a signal is recorded, so that the next one takes over
when the owner leaves.

Do not read thread-local storage on a thread that never ran PHP, which can
allocate on first access when PHP is a shared library, and keep the original
handlers saved by an earlier startup.
A signal delivered to a PHP thread that has no handler for it is now forwarded
to a thread that does, instead of taking the default action or being lost.

Without zend signals, the disposition of a signal is process-wide, so it is only
reset when no other thread handles the signal. The change and the registrations
are kept consistent under the forwarding lock.

Use tsrm_sigmask() in pcntl_signal_dispatch(), as sigprocmask() changes the mask
of every thread on macOS.
Without zend signals, zend_timeout_handler() printed a message and lost the
timeout, and SA_RESETHAND left the default action for the next signal. Forward
the signal to the thread that armed the timer instead, and keep the handler
installed under ZTS.
Cover a signal delivered to a thread that never ran PHP, handover between the
threads that handle a signal, an owner that exits, concurrent registration and
fork, with and without zend signals.

No job tested the build without zend signals, so use it in the nightly variation
job.
Recording every zend_sigaction() started the helper thread in each ZTS request,
which makes unshare(CLONE_NEWUSER) fail. Register pcntl handlers and running
execution timers explicitly instead.

A timer does not keep a signal disposition in place for other threads, so that a
thread cannot keep forwarding a signal to itself.

When the owner has left, send the signal to the process again so that it takes
its current action, and hand over a signal that the leaving thread blocks. Do not
let one thread's SIG_IGN disable the handler of another.

Fix double frees when a thread exits during shutdown or in a forked child, and
synchronize the initialization check.
Keep the forwarding infrastructure in Zend/zend_signal_forward.c, with a small
API, and define its policy: the owner of a signal is the thread that most
recently registered a handler for it, or otherwise a thread with an armed timer.

Do not call raise(), fprintf() or SIGG() on a thread without TSRM storage.

Timer signals carry a generation, so a forward delayed past a re-armed timer is
dropped, and the signal of a timer that was just disarmed no longer ends the
process. A timer signal reaching a thread without a time limit goes to the thread
that armed the timer.

Without an owner, a signal takes its default action instead of being lost in a
forked child. Releasing a handler keeps the disposition that an armed timer or a
thread ignoring the signal still needs.

Requests that register nothing no longer take the forwarding mutex. A forked child
uses a new mutex instead of initializing a possibly locked one.
@phcorp phcorp changed the title Fix GH-25541: pcntl handler crashes on a thread that never ran PHP Fix GH-25541, GH-25548, GH-25549: forward signals from threads without PHP context Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants