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

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
rfc:additional-context-in-pcntl-signal-handler [2016/06/16 02:13]
bishop created
rfc:additional-context-in-pcntl-signal-handler [2017/09/22 13:28] (current)
Line 1: Line 1:
 ====== PHP RFC: Additional Context in pcntl_signal Handler ====== ====== PHP RFC: Additional Context in pcntl_signal Handler ======
-  * Version: 0.1+  * Version: 1.0
   * Date: 2016-06-14   * Date: 2016-06-14
-  * Author: David Walker <dave@mudsite.com>, Bishop Bettini <bishop@php.net> +  * Authors: David Walker <dave@mudsite.com>, Bishop Bettini <bishop@php.net> 
-  * Status: Draft+  * Status: Accepted
   * First Published at: http://wiki.php.net/rfc/additional-context-in-pcntl-signal-handler   * First Published at: http://wiki.php.net/rfc/additional-context-in-pcntl-signal-handler
  
  
 ===== Introduction ===== ===== Introduction =====
-Modern UNIX kernels include additional context when delivering a signal, however the callable handler for [[http://php.net/manual/en/function.pcntl-signal.php|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.+Modern UNIX kernels include additional, contextual information when delivering a signal, however the callable handler for [[http://php.net/manual/en/function.pcntl-signal.php|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 ===== ===== Proposal =====
-Currently the signal handler receives only one formal argument, the [[http://man7.org/linux/man-pages/man7/signal.7.html|number of the signal]] sent. This proposal would add a second formal argument, an array of signal info as provided by the kernel, as seen here:+Currently the signal handler receives only one formal argument, the [[http://man7.org/linux/man-pages/man7/signal.7.html|number of the signal]] sent. This proposal would add a second formal argument, an array of signal info as provided by the underlying system'kernel
 + 
 +One possible use case is identifying the process ID of the signal //sender//[[http://serverfault.com/a/94995/204816|described at the C level in this StackOverflow Q&A]] and implemented in PHP as seen here:
  
 <file php> <file php>
 <?php <?php
 pcntl_signal(SIGUSR1, function ($signo, $siginfo) { pcntl_signal(SIGUSR1, function ($signo, $siginfo) {
-    print_r($siginfo);+    printf('USR1 from %s', $siginfo['pid'] ?? 'unknown');
 }); });
-posix_kill(0, SIGUSR1);+posix_kill(posix_getpid(), SIGUSR1); 
 +pcntl_signal_dispatch();
 </file> </file>
 +
 +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 [[https://www.mkssoftware.com/docs/man5/siginfo_t.5.asp|one or more of the following keys]], depending upon the system support for signal information and the nature of the sent signal: The ''$siginfo'' array may contain [[https://www.mkssoftware.com/docs/man5/siginfo_t.5.asp|one or more of the following keys]], depending upon the system support for signal information and the nature of the sent signal:
  
-  * ''si_signo'', the signal number being sent (duplicates the first argument). +  * **''signo''**, the signal number being sent (duplicates the first argument to the handler). 
-  * ''si_code'', the signal code, which depends upon the signal sent and provides context-specific reason //why// the signal was sent. +  * **''code''**, the signal code, which depends upon the signal sent and provides context-specific reason //why// the signal was sent. 
-  * ''si_value'', the value for the code, if appropriate.+  * **''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.
  
-These are generally useful to a wide range of process interactions.+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 [[https://standards.ieee.org/findstds/standard/1003.1-2001.html|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.
  
  
Line 38: Line 52:
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
  
-Next PHP 7.x.+Next PHP 7.x, currently 7.1.
  
  
Line 44: Line 58:
 ==== To SAPIs ==== ==== To SAPIs ====
  
-TODO+None.
  
  
Line 54: Line 68:
 ==== To Opcache ==== ==== To Opcache ====
  
-TODO+None.
  
 +===== Discussion =====
  
-===== Open Issues =====+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 [[https://github.com/php/php-src/pull/1985|PR]] addressed parts of the suggestion. [[https://www.mail-archive.com/internals@lists.php.net/msg86504.html|Reference.]]
  
-  * Should we send ''null'' if the underlying system doesn't support ''siginfo_t''or should we send ''array ()''? +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 functionset the handlerand triggered the signal. Passing the additional information resulted in 2000 extra instructions, out of total 13 million. This seems negligible compared to the cost of acquiring the same information through other means (eg message queuestemporary files, etc.).
-  * Should we normalize the array keys (for example''si_signo'' is removed because it'duplicateand ''si_code'' becomes just ''code'')+
-  * Are there any effects to opcache or web SAPI?+
  
 +===== Open Issues =====
 +
 +None.
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
Line 70: Line 86:
 Requires a 50%+1 majority. Requires a 50%+1 majority.
  
 +<doodle title="Provide additional context in pcntl signal handler?" auth="bishopb" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
 +
 +Voting shall close one week after opening on Thursday, July 14, 2016 at 23:59 UTC.
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
  
-  * [[https://github.com/bp1222/php-src|Work in Progress]]+  * [[https://github.com/php/php-src/pull/1993|Implementation with tests.]]
  
  
Line 79: Line 101:
  
   * [[https://marc.info/?l=php-internals&m=146584196929126&w=2|Initial ping to php.internals]]   * [[https://marc.info/?l=php-internals&m=146584196929126&w=2|Initial ping to php.internals]]
 +  * [[https://marc.info/?l=php-internals&m=146670242109688&w=2|Discussion]]
rfc/additional-context-in-pcntl-signal-handler.1466043185.txt.gz · Last modified: 2017/09/22 13:28 (external edit)