Document rc separation

Author: iluuu1994

docs/source/core/data-structures/reference-counting.rst

@@ -5,17 +5,17 @@
 In languages like C, when you need memory for storing data for an indefinite period of time or in a
 large amount, you call ``malloc`` and ``free`` to acquire and release blocks of memory of some size.
 This sounds simple on the surface but turns out to be quite tricky, mainly because the data may not
-be freed for as long as it is used, anywhere in the program. Sometimes, this makes it unclear who is
+be freed for as long as it is used anywhere in the program. Sometimes this makes it unclear who is
 responsible for freeing the memory, and when to do so. Failure to handle this correctly may result
-in use-after-free, double-free, and memory leaks.
+in a use-after-free, double-free, or memory leak.
 
-Very rarely do you have to think about memory management when working in PHP. The engine takes care
-of this for you by tracking which values are no longer needed. It does this by assigning a reference
-count to each value, often abbreviated as refcount or RC. Whenever a reference to a value is passed
-to somebody else, its reference count is increased to indicate the value is now used by another
-party. When the party no longer needs the value, it is responsible for decreasing the reference
-count. Once the reference count reaches zero, we know the value is no longer needed anywhere in the
-program, and that it may be freed.
+In PHP you usually do not need to think about memory management. The engine takes care of allocating
+and freeing memory for you by tracking which values are no longer needed. It does this by assigning
+a reference count to each allocated value, often abbreviated as refcount or RC. Whenever a reference
+to a value is passed somewhere else, its reference count is increased to indicate the value is now
+used by another party. When the party no longer needs the value, it is responsible for decreasing
+the reference count. Once the reference count reaches zero, we know the value is no longer needed
+anywhere, and that it may be freed.
 
 .. code:: php
 
@@ -33,9 +33,9 @@ Reference counting is needed for types that store auxiliary data, which are the
 -  Resources
 
 These are either reference types (objects, references and resources) or they are large types that
-don't fit in a single ``zend_value`` directly (strings, arrays). More simple types either don't
-store a value at all (``null``, ``false``, ``true``) or their value is small enough to fit directly
-in ``zend_value`` and copied when passed somewhere else (``int``, ``float``).
+don't fit in a single ``zend_value`` directly (strings, arrays). Simpler types either don't store a
+value at all (``null``, ``false``, ``true``) or their value is small enough to fit directly in
+``zend_value`` (``int``, ``float``).
 
 All of the reference counted types share a common initial struct sequence.
 
@@ -58,10 +58,6 @@ All of the reference counted types share a common initial struct sequence.
         // ...
     };
 
-This explains the ``zval.value.counted`` union member in the ``zval`` struct we saw in the ``zval``
-chapter. It refers to the initial ``gc`` field of any reference counted type, in case we don't care
-about which concrete type we're dealing with.
-
 The ``zend_refcounted_h`` struct is simple. It contains the reference count, and a ``type_info``
 field that repeats some of the type information that is also stored in the ``zval``, for situations
 where we're not dealing with a ``zval`` directly. It also stores some additional fields, described
@@ -135,10 +131,25 @@ naming is not always consistent.
  Separation
 ************
 
-..
-   ::
+PHP has value and reference types. Reference types are types that are shared through a reference, a
+"pointer" to the value, rather than the value itself. Modifying such a value in one place changes it
+for all of its observers. For example, writing to a property changes the property in every place the
+object is referenced. Value types, on the other hand, are copied when passed to another party.
+Modifying the original value does not affect the copy, and vice versa.
+
+In PHP, arrays and strings are value types. Since they are also reference counted types, this
+requires some special care when modifying values. In particular, we need to make sure that modifying
+the value is not observable from other places. Modifying a value with RC 1 is unproblematic, since
+we are the values sole owner. However, if the value has a reference count of >1, we need to create a
+fresh copy before modifying it. This process is called separation or CoW (copy on write).
+
+.. code:: php
 
-   _TODO
+   $a = [1, 2, 3]; // RC 1
+   $b = $a;        // RC 2
+   $b[] = 4;       // Separation, $a RC 1, $b RC 1
+   var_dump($a);   // [1, 2, 3]
+   var_dump($b);   // [1, 2, 3, 4]
 
 ***********************************
  Immutable reference counted types