php-doc-en/reference/pthreads/examples.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 327532 $ -->

<chapter xml:id="pthreads.tutorials" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;

 <section role="examples">
  <para>This HelloWorld example demonstrates how simple it is to define and execute Threads in PHP applications.</para>
  <example>
   <title>Hello World Example</title>
   <programlisting role="php">
<![CDATA[
<?php
class HelloWorld extends Thread {
    public function __construct($world) {
       $this->world = $world;
    }

    public function run() {
        return sprintf("Hello %s", $this->world);
    }
}

$thread = new HelloWorld("World");

if ($thread->start()) {
    printf("Thread #%lu says: %s\n", $thread->getThreadId(), $thread->join());
}
?>
]]>
   </programlisting>
  </example>
 </section>

 <section role="examples">
  <para>
   The purpose of PHP is to generate content, having Threading in the toolbox
   makes more content available. But content is a relative subject, for this
   reason good control is needed over when a Thread is allowed to execute,
   or indeed, forced to wait.
  </para>
  <para>
   For example, a meta search engine may have to carry out the following:
  </para>
  <orderedlist>
   <listitem>
    <para>
     Initiate a search with primary source of data
    </para>
   </listitem>
   <listitem>
    <para>
     Log results of API usage for statistical analysis
    </para>
   </listitem>
   <listitem>
    <para>
     Cache results to limit external API usage
    </para>
   </listitem>
   <listitem>
    <para>
     Query local databases to generate page content - recent searches etc
    </para>
   </listitem>
   <listitem>
    <para>
     Log results of local database usage, HTTP usage, cache usage and 
     possibly fall back to secondary source and goto 2;
    </para>
   </listitem>
   <listitem>
    <para>
     Generate content ( HTML ) from API output, xml/json etc
    </para>
   </listitem>
   <listitem>
    <para>
     Send content to client
    </para>
   </listitem>
  </orderedlist>
  <para>
   In a multi-threaded design, the Thread delegated Task 2 cannot possibly run
   until Thread 1 has returned a result.
  </para>
  <para>
   In an extreme design, where each Task is allocated a Thread, Threads 2,3,4,5
   and even 6 can all be run concurrently, but they all depend on Thread 1
   returning content.
  </para>
  <para>
   pthreads includes an easy to use way to synchronize when Threads are allowed
   to execute, or forced to wait, to allow flexible, powerful multi-threading
   whether being used for a Search Engine or Administration ( ie. cron jobs ).
  </para>
  <example>
  <title>Synchronization</title>
  <programlisting role="php">
<![CDATA[
<?php
class Task1 extends Thread {
    public function __construct($params) {
        $this->params = $params;
    }
  
    /* ... */
  
    public function run() {

       /* do some admin possibly here, maybe lookup local caches, check if the client is googlebot etc */
       if ($this->ensureAvailabiilty()) {
           $this->notify();
           return $this->resultSet();
       }
    }
}
 
class Task2 extends Thread {
    public function __construct($task1, $params) {
        $this->task1 = $task1;
        $this->params = $params;
    }
  
    /* ... */
  
    public function run(){
    $task1 = Thread::getThread($this->task1);
        if ($task1->wait()) {
            $this->createLogs();
        }
    }
}
 
$tasks    = array();
$tasks[0] = new Task1($_POST);
$tasks[1] = new Task2($tasks[0]->getThreadId(), $_POST);
/* ... */
 
foreach ($tasks as $id => $task) {
    $task->start();
}
 
/* ... */
?>
]]>
   </programlisting>
   </example>
   <para>
    Using the wait/notify mechanism included in pthreads hides the complexity of
    using Mutex and Condition Variables to synchronize Threads, greatly simplifies
    readability and more importantly maintainability of an idea or implementation.
   </para>
 </section>

 <section role="examples">
  <para>
   pthreads allows direct access to ( a subset of ) both of these features.
   The programmer should take care to destroy Mutex and Condition Variable
   handles that are no longer required for their logic.
  </para>
  <para>
   Mutex and Condition Variables are not destroyed on behalf of the programmer
   like other resources in PHP, as this would limit their usefulness in the
   context of multi-threading in SAPI environments.
  </para>
  <para>
   They are easily stored and passed around as they are represented as long numbers.
   Mutex and Condition Variables persist once allocated until they are explicitly
   destroyed.
  </para>
  <example>
  <title>Mutex and Condition Variables</title>
  <programlisting role="php">
<![CDATA[
<?php
/* ... */
if (Cond::broadcast($finished)) {
    Cond::destroy($finished);
    Mutex::destroy($signals);
}
?>
]]>
  </programlisting>
  </example>
  <para>
   The snippet above shows a PHP script sending it's final broadcast to the Threads
   it has created and cleaning up the Condition Variable it created and used for
   the broadcast. Other Threads that were waiting for a signal on $finished were
   using $signals - waiting for a signal always requires a Mutex - and as the
   Condition Variable is no longer valid, the accompanying Mutex is also destroyed.
  </para>
  <para>
  <warning>
   <para>
    Before the programmer attempts to use Condition Variables they should have
    knowledge of "Spurious Wakeups" as allowed for in the Posix Threads
    specification upon which pthreads is built.
   </para>
   <para>
    A brief explanation of the problem is as follows:
   </para>
   <para>
    A call to Cond::wait may return before the Condition Variable receives a
    legitimate signal as a result of another context calling Cond::signal
    or Cond::broadcast. Because of this behavior, a call to wait for a
    signal on a Condition Variable must check a predicate (usually a boolean
    value) upon returning from the call to Cond::wait. This eliminates the
    risk of Spurious Wakeups.
   </para>
  </warning>
  </para>
 </section>
 
 <section role="examples">
 <title>Thread Members</title>
 <para>
  The members of a Thread can be of any type that PHP supports the serialization
  of, including programmer declared classes.
 </para>
 <para>
  In the case where a Thread contains members that are of a programmer declared
  type (class), the programmer must include the declaration using Thread::__prepare
  magic method.
 </para>
 <para>
  Thread::__prepare method is executed by pthreads in the newly created context,
  before the newly created context executes Thread::run. This results in correct
  deserialization of the programmer declared type in the new context.
 </para>
 <example>
 <programlisting role="php">
<![CDATA[
<?php
class ExampleThread extends Thread {
    public function __prepare(){
        require_once("/path/to/inc.php");
    }

    public function __construct($myType){
        $this->myType = $myType;
    }

    public function run(){
        if (method_exists($this->myType, "myMethod")) {
    
        }
   }
}

require_once("/path/to/inc.php");
/* ... */

$my = new Inc();
/* ... */

$example = new ExampleThread($my);
if ($example->start()) {
    /* ... */
}
?>
]]>
  </programlisting>
  </example>
  <para>
   In the example above, /path/to/inc.php declares a class, as defined by the
   programmer. The programmer includes the declaration in the global scope
   before passing an instance of the object to an instance of ExampleThread.
   The instance of ExampleThread is able to manipulate the object and execute
   member functions having included the declaration using __prepare magic.
  </para>
 </section>
</chapter>

<!-- 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:"~/.phpdoc/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
-->