pcntl_signal: Switch to pcntl_async_signals and improve documentation (#4539)

Author: AllenJB

reference/pcntl/examples.xml

@@ -12,7 +12,7 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-declare(ticks=1);
+pcntl_async_signals(true);
 
 $pid = pcntl_fork();
 if ($pid == -1) {

reference/pcntl/functions/pcntl-signal.xml

@@ -135,8 +135,7 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-// tick use required
-declare(ticks = 1);
+pcntl_async_signals(true);
 
 // signal handler function
 function sig_handler($signo)
@@ -189,13 +188,31 @@ echo "Done\n";
   <para>
    <function>pcntl_signal</function> doesn't stack the signal handlers, but replaces them.
   </para>
+  <refsect2>
+   <title>Dispatch Methods</title>
+   <para>
+    There are several methods of dispatching signal handlers:
+    <simplelist>
+     <member>Asynchronous dispatch with <function>pcntl_async_signals</function> enabled. This is the recommended method</member>
+     <member>Setting <link linkend="control-structures.declare.ticks">tick</link> frequency</member>
+     <member>Manual dispatch with <function>pcntl_signal_dispatch</function></member>
+    </simplelist>
+   </para>
+   <para>
+    When signals are dispatched asynchronously or using tick-based execution, blocking functions like
+    <function>sleep</function> may be interrupted.
+   </para>
+  </refsect2>
  </refsect1><!-- }}} -->
 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><link xlink:href="https://en.wikipedia.org/wiki/Signal_(IPC)">Signal (IPC)</link> on Wikipedia</member>
+    <member><function>pcntl_async_signals</function></member>
     <member><function>pcntl_fork</function></member>
+    <member><function>pcntl_signal_dispatch</function></member>
     <member><function>pcntl_waitpid</function></member>
    </simplelist>
   </para>