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

<book xml:id="book.pthreads" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <?phpdoc extension-membership="pecl" ?>
 <title>pthreads</title>
 <titleabbrev>pthreads</titleabbrev>

 <preface xml:id="intro.pthreads">
  &reftitle.intro;
  <para>
   pthreads is an object-orientated API that provides all of the tools needed
   for multi-threading in PHP. PHP applications can create, read, write,
   execute and synchronize with Threads, Workers and Threaded objects.
  </para>
  <warning>
   <simpara>
    This extension is considered unmaintained and dead.
   </simpara>
  </warning>
  <tip>
   <simpara>
    Consider using <link linkend="book.parallel">parallel</link> instead.
   </simpara>
  </tip>
  <warning>
   <para>
    The pthreads extension cannot be used in a web server environment.
    Threading in PHP is therefore restricted to CLI-based applications only.
   </para>
  </warning>
  <warning>
   <para>
    pthreads (v3) can only be used with PHP 7.2+: This is due to ZTS
    mode being unsafe in 7.0 and 7.1.
   </para>
  </warning>
  <para>
   The <classname>Threaded</classname> class forms the basis of the
   functionality that allows pthreads to operate. It exposes synchronization
   methods and some useful interfaces for the programmer.
  </para>
  <para>
   The <classname>Thread</classname> class enables for threads to be created by
   simply extending it and implementing a <literal>run</literal> method. Any
   members can be written to and read by any context with a reference to the
   thread. Any context can also execute any public and protected methods. 
   The body of the run method will be executed in a separate thread when the
   <methodname>Thread::start</methodname> method of the implementation is
   called from the context that created it. Only the context that creates a
   thread can start and join it.
  </para>
  <para>
   The <classname>Worker</classname> class has a persistent state, and will be
   available from the call to <methodname>Thread::start</methodname> (an
   inherited method) until the object goes out of scope, or is explicitly
   shutdown (via <methodname>Worker::shutdown</methodname>). Any context with a
   reference to the worker object can stack tasks onto the Worker (via 
   <methodname>Worker::stack</methodname>), where these tasks will be executed
   by the worker in a separate thread. The <literal>run</literal> method of a
   worker object will be executed before any objects on the worker's stack,
   enabling for resources to be initialized that the objects to be executed may
   need.
  </para>
  <para>
   The <classname>Pool</classname> class is used to create a group of workers
   to distribute <classname>Threaded</classname> objects amongst them. It is
   the easiest and most efficient way of using multiple threads in PHP
   applications.
  </para>
  <caution>
   <para>
    The <classname>Pool</classname> class does not extend the
    <classname>Threaded</classname> class, and so pool-based objects are
    considered a normal PHP objects. As such, its instances of it should not be
    shared amongst different contexts.
   </para>
  </caution>
  <para>
   The <classname>Volatile</classname> class is new to pthreads v3. It is used
   to denote mutable <classname>Threaded</classname> properties of
   <classname>Threaded</classname> classes (since these are now immutable by
   default). It is also used to store PHP arrays in
   <classname>Threaded</classname> contexts.
  </para>
  <para>
   Synchronization is an important ability when threading. All of the objects
   that pthreads creates have built in synchronization in the (which will be
   familiar to java programmers) form of
   <methodname>Threaded::wait</methodname> and
   <methodname>Threaded::notify</methodname>. Calling
   <methodname>Threaded::wait</methodname> on an object will cause the context
   to wait for another context to call
   <methodname>Threaded::notify</methodname> on the same object. This mechanism
   allows for powerful synchronization between <classname>Threaded</classname>
   objects in PHP.
  </para>
  <caution>
  <para>
   Any objects that are intended for use in the multi-threaded parts of your
   application should extend <classname>Threaded</classname>.
  </para>
  </caution>
  <para>
 Data Storage:
 As a rule of thumb, any data type that can be serialized can be used as a member of a Threaded object, it can be read and written from any context with a reference to the Threaded Object. 
 Not every type of data is stored serially, basic types are stored in their true form. 
 Complex types, Arrays, and Objects that are not Threaded are stored serially; they can be read and written to the Threaded Object from any context with a reference.
 With the exception of Threaded Objects any reference used to set a member of a Threaded Object is separated from the reference in the Threaded Object; 
 the same data can be read directly from the Threaded Object at any time by any context with a reference to the Threaded Object.
  </para>
  <para>
 Static Members:
 When a new context is created ( Thread or Worker ), they are generally copied, but resources and objects with internal state are nullified (for safety reasons). This allows them to function as a kind of thread local storage. For example, upon starting the context, a class whose static members include connection information for a database server, and the connection itself, will only have the simple connection information copied, not the connection. Allowing the new context to initiate a connection in the same way as the context that created it, storing the connection in the same place without affecting the original context.
  </para>
  <caution>
  <para>
 When print_r, var_dump and other object debug functions are executed, they do not include recursion protection.
  </para>
  </caution>
  <note>
   <para>
 Resources:
 The extensions and functionality that define resources in PHP are completely unprepared for this kind of environment; pthreads makes provisions for Resources to be shared among contexts, however, for most types of resource it should be considered unsafe. Extreme caution and care should be used when sharing resources among contexts.
   </para>
  </note>
  <caution>
   <para>
 In the environment which pthreads executes, some restrictions and limitations are necessary in order to provide a stable environment.
   </para>
  </caution>
 </preface>
 
 &reference.pthreads.setup;
 &reference.pthreads.constants;
 &reference.pthreads.threaded;
 &reference.pthreads.thread;
 &reference.pthreads.worker;
 &reference.pthreads.collectable;
 &reference.pthreads.pool;
 &reference.pthreads.volatile;

</book>

<!-- 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
-->
