rfc:additional-context-in-pcntl-signal-handler

This is an old revision of the document!


PHP RFC: Additional Context in pcntl_signal Handler

Introduction

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.

Proposal

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(0, SIGUSR1);

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.

Backward Incompatible Changes

There are no backward compatibility breaks.

Proposed PHP Version(s)

Next PHP 7.x.

RFC Impact

To SAPIs

None.

To Existing Extensions

The pcntl extension will be updated.

To Opcache

None.

Open Issues

None.

Proposed Voting Choices

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

Requires a 50%+1 majority.

Patches and Tests

References

rfc/additional-context-in-pcntl-signal-handler.1466438867.txt.gz · Last modified: 2017/09/22 13:28 (external edit)