diff --git a/reference/pthreads/book.xml b/reference/pthreads/book.xml
index c7a024275a..fc5edf17f3 100644
--- a/reference/pthreads/book.xml
+++ b/reference/pthreads/book.xml
@@ -69,7 +69,8 @@
The Volatile class is new to pthreads v3. It is used
to denote mutable Threaded properties of
Threaded classes (since these are now immutable by
- default).
+ default). It is also used to store PHP arrays in
+ Threaded contexts.
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;
diff --git a/reference/pthreads/volatile.xml b/reference/pthreads/volatile.xml
new file mode 100644
index 0000000000..6a8b115692
--- /dev/null
+++ b/reference/pthreads/volatile.xml
@@ -0,0 +1,139 @@
+
+
+
+
+
+ The Volatile class
+ Volatile
+
+
+
+
+
+ &reftitle.intro;
+
+ The Volatile class is new to pthreads v3. Its
+ introduction is a consequence of the new immutability semantics of
+ Threaded members of Threaded
+ classes. The Volatile class enables for mutability
+ of its Threaded members, and is also used to store
+ PHP arrays in Threaded contexts.
+
+
+
+
+
+ &reftitle.classsynopsis;
+
+
+
+ Volatile
+
+
+
+
+ Volatile
+
+
+
+ extends
+ Threaded
+
+
+
+ Collectable
+
+
+
+ Traversable
+
+
+
+
+
+
+
+
+
+ New immutability semantics of Threaded
+
+data = new Threaded();
+
+ // attempt to overwrite a Threaded property of a Threaded class (invalid)
+ $this->data = new StdClass();
+ }
+}
+
+var_dump((new Task())->data);
+]]>
+
+ &example.outputs.similar;
+
+
+
+
+
+ Volatile use-case
+
+data = new Threaded();
+
+ // attempt to overwrite a Threaded property of a Volatile class (valid)
+ $this->data = new StdClass();
+ }
+}
+
+var_dump((new Task())->data);
+]]>
+
+ &example.outputs.similar;
+
+
+
+
+
+
+
+
+ &reference.pthreads.entities.volatile;
+
+
+
+