php-doc-en/reference/pcntl/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
 <reference id="ref.pcntl">
  <title>Process Control Functions</title>
  <titleabbrev>PCNTL</titleabbrev>

  <partintro>
   <section id="pcntl.intro">
    &reftitle.intro;
    <para>
     Process Control support in PHP implements the Unix style of
     process creation, program execution, signal handling and process
     termination. Process Control should not be enabled within a
     webserver environment and unexpected results may happen if any
     Process Control functions are used within a webserver environment.
    </para>
    <para>
     This documentation is intended to explain the general usage of
     each of the Process Control functions. For detailed information
     about Unix process control you are encouraged to consult your
     systems documentation including fork(2), waitpid(2) and signal(2)
     or a comprehensive reference such as Advanced Programming in the
     UNIX Environment by W. Richard Stevens (Addison-Wesley).
    </para>
    <para>
     PCNTL now uses ticks as the signal handle callback mechanism, which is
     much faster than the previous mechanism. This change follows the same
     semantics as using "user ticks". You use the <function>declare</function> 
     statement to specify the locations in your program where callbacks are
     allowed to occur. This allows you to minimize the overhead of handling
     asynchronous events. In the past, compiling PHP with pcntl enabled would
     always incur this overhead, whether or not your script actually used
     pcntl.
    </para>
    <para>
     There is one adjustment that all pcntl scripts prior to PHP 4.3.0 must
     make for them to work which is to either to use
     <function>declare</function> on a section where you wish to allow
     callbacks or to just enable it across the entire script using 
     the new global syntax of <function>declare</function>.
    </para>

    &note.no-windows.extension;
   </section>

   <section id="pcntl.requirements">
    &reftitle.required;
    &no.requirement;
   </section>

   &reference.pcntl.configure;

   <section id="pcntl.configuration">
    &reftitle.runtime;
    &no.config;
   </section>

   <section id="pcntl.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   &reference.pcntl.constants;

   <section id="pcntl.example">
    &reftitle.examples;
    <para>
     This example forks off a daemon process with a signal handler.
    </para>
    <example>
     <title>Process Control Example</title>
     <programlisting role="php">
<![CDATA[
<?php
declare(ticks=1);

$pid = pcntl_fork();
if ($pid == -1) {
     die("could not fork"); 
} else if ($pid) {
     exit(); // we are the parent 
} else {
     // we are the child
}

// detatch from the controlling terminal
if (!posix_setsid()) {
    die("could not detach from terminal");
}

// setup signal handlers
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");

// loop forever performing tasks
while (1) {

    // do something interesting here

}

function sig_handler($signo) 
{

     switch ($signo) {
         case SIGTERM:
             // handle shutdown tasks
             exit;
             break;
         case SIGHUP:
             // handle restart tasks
             break;
         default:
             // handle all other signals
     }

}

?>
]]>
     </programlisting>
    </example>
   </section>

   <section id="pcntl.seealso">
    &reftitle.seealso;
    <para>
     A look at the section about
     <link linkend="ref.posix">POSIX functions</link>
     may be useful.
    </para>
   </section>

  </partintro>

&reference.pcntl.functions;

 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->