Pthreads: document Volatile class

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@342862 c90b9560-bf6c-de11-be94-00142212c4b1

reference/pthreads/book.xml

@@ -69,7 +69,8 @@
    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).
+   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
@@ -129,6 +130,7 @@
  &reference.pthreads.pool;
  &reference.pthreads.mutex;
  &reference.pthreads.cond;
+ &reference.pthreads.volatile;
 
 </book>
 

reference/pthreads/volatile.xml

@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<phpdoc:classref xml:id="class.volatile" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <title>The Volatile class</title>
+ <titleabbrev>Volatile</titleabbrev>
+  
+ <partintro>
+
+<!-- {{{ Volatile intro -->
+  <section xml:id="volatile.intro">
+   &reftitle.intro;
+   <para>
+    The <classname>Volatile</classname> class is new to pthreads v3. Its
+    introduction is a consequence of the new immutability semantics of
+    <classname>Threaded</classname> members of <classname>Threaded</classname>
+    classes. The <classname>Volatile</classname> class enables for mutability
+    of its <classname>Threaded</classname> members, and is also used to store
+    PHP arrays in <classname>Threaded</classname> contexts.
+   </para>
+  </section>
+<!-- }}} -->
+
+  <section xml:id="volatile.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>Volatile</classname></ooclass>
+
+<!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+      <classname>Volatile</classname>
+     </ooclass>
+     
+     <ooclass>
+      <modifier>extends</modifier>
+      <classname>Threaded</classname>
+     </ooclass>
+     
+     <oointerface>
+      <interfacename>Collectable</interfacename>
+     </oointerface>
+
+     <oointerface>
+      <interfacename>Traversable</interfacename>
+     </oointerface>
+    </classsynopsisinfo>
+   </classsynopsis>
+<!-- }}} -->
+
+  </section>
+
+  <section xml:id="volatile.examples">
+   <example xml:id="volatile.example.immutable"><!-- {{{ -->
+    <title>New immutability semantics of Threaded</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+class Task extends Threaded
+{
+    public function __construct()
+    {
+        $this->data = new Threaded();
+
+        // attempt to overwrite a Threaded property of a Threaded class (invalid)
+        $this->data = new StdClass();
+    }
+}
+
+var_dump((new Task())->data);
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+RuntimeException: Threaded members previously set to Threaded objects are immutable, cannot overwrite data in %s:%d
+]]>
+    </screen>
+   </example><!-- }}} -->
+   <example xml:id="volatile.example.basic"><!-- {{{ -->
+    <title>Volatile use-case</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+class Task extends Volatile
+{
+    public function __construct()
+    {
+        $this->data = new Threaded();
+
+        // attempt to overwrite a Threaded property of a Volatile class (valid)
+        $this->data = new StdClass();
+    }
+}
+
+var_dump((new Task())->data);
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+object(stdClass)#3 (0) {
+}
+]]>
+    </screen>
+   </example><!-- }}} -->
+  </section>
+
+ </partintro>
+
+ &reference.pthreads.entities.volatile;
+
+</phpdoc:classref>
+
+<!-- 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
+-->