PHP RFC: Additional Context in pcntl_signal Handler

• Version: 1.0
• Date: 2016-06-14
• Authors: David Walker dave@mudsite.com, Bishop Bettini bishop@php.net
• Status: Accepted
• First Published at: http://wiki.php.net/rfc/additional-context-in-pcntl-signal-handler

Modern UNIX kernels include additional, contextual information when delivering a signal, however the callable handler for pcntl_signal does not receive this information. Developers coordinating multiple processes through signals must arrange to gather and send this same information using alternative channels, which is time-consuming, error-prone, and unnecessary.

Currently the signal handler receives only one formal argument, the number of the signal sent. This proposal would add a second formal argument, an array of signal info as provided by the underlying system's kernel.

One possible use case is identifying the process ID of the signal sender, described at the C level in this StackOverflow Q&A and implemented in PHP as seen here:

<?php
pcntl_signal(SIGUSR1, function ($signo, $siginfo) {
    printf('USR1 from %s', $siginfo['pid'] ?? 'unknown');
});
posix_kill(posix_getpid(), SIGUSR1);
pcntl_signal_dispatch();

Other uses cases include identifying the cause of the signal (such as asynchronous I/O or timer expiration), identifying the sending user, and finding the consumed user & system time of an exited process.

The $siginfo array may contain one or more of the following keys, depending upon the system support for signal information and the nature of the sent signal:

• signo, the signal number being sent (duplicates the first argument to the handler).
• code, the signal code, which depends upon the signal sent and provides context-specific reason why the signal was sent.
• value, the value for the code, if appropriate for the code.
• errno, the error number associated with the signal, if appropriate for the signal and non-zero.
• pid, the process ID of the signal sender, if appropriate for the signal.
• uid, the real user ID of the signal sender, if appropriate for the signal.
• addr, the address at which the faulting signal occurred: only faulting signals like SIGFPE include this.
• status, the status code of an exiting process: only exiting signals like SIGCHLD include this.
• band, the asynchronous I/O band, if appropriate for the signal.
• mtime, the time of last data modification, if appropriate for the signal.

The naming of $siginfo and its keys comes from the pcntl_sigwaitinfo implementation. (So for example, “signo” in PHP comes from “si_signo” in the C structure, the leading “si_” having been removed by the PHP engine.) Name normalization does not apply to the values of the code field, as those represent system-specific values that follow no normative naming convention.

Some older systems not conforming to POSIX.1-2001 (where this structure was formally codified) may not support passing the additional context. In such case, PHP will pass null as the second argument to the handler.

There are no backward compatibility breaks.

Next PHP 7.x, currently 7.1.

None.

The pcntl extension will be updated.

None.

Instead of updating pcntl_signal, it was suggested to add a method pcntl_sigaction, which would “keep maximum compatibility and eliminate unnecessary additional overhead”. This suggestion was later withdrawn as perhaps adding more complication than the patch itself, though a later PR addressed parts of the suggestion. Reference.

Performance was raised as a concern. Having run tests through callgrind there is an additional 0.0001% cost for the feature. The profiled code defined an empty function, set the handler, and triggered the signal. Passing the additional information resulted in 2000 extra instructions, out of a total 13 million. This seems negligible compared to the cost of acquiring the same information through other means (eg message queues, temporary files, etc.).

None.

Vote shall be Yes or No to deliver kernel-provided additional context to the pcntl_signal handler.

Requires a 50%+1 majority.

Provide additional context in pcntl signal handler?
Real name	Yes	No
bishop (bishop)
bwoebi (bwoebi)
colinodell (colinodell)
guilhermeblanco (guilhermeblanco)
jgmdev (jgmdev)
jpauli (jpauli)
kguest (kguest)
kinncj (kinncj)
marcio (marcio)
mbeccati (mbeccati)
mike (mike)
stas (stas)
svpernova09 (svpernova09)
trowski (trowski)
tyrael (tyrael)
Final result:	15	0
This poll has been closed.

Voting shall close one week after opening on Thursday, July 14, 2016 at 23:59 UTC.

• Implementation with tests.

• Initial ping to php.internals
• Discussion