Simplify zval chapter

Author: iluuu1994

docs/source/core/data-structures/zval.rst

@@ -2,11 +2,38 @@
  zval
 ######
 
-PHP is a dynamic language. As such, a variable can typically contain a value of any type, and the
-type of the variable may even change during the execution of the program. Under the hood, this is
-implemented through the ``zval`` struct. It is one of the most important data structures in php-src.
-It is essentially a "tagged union", meaning it consists of an integer tag, representing the type of
-the variable, and a union for the value itself. Let's look at the value first.
+PHP is a dynamic language. A variable can typically contain a value of any type, and the type of the
+variable may even change during the execution of the program. Under the hood, this is implemented
+through the ``zval`` struct. It is one of the most important data structures in php-src. It is
+implemented as a "tagged union", meaning it stores what type of value it contains, and the value
+itself. Let's look at the type first.
+
+************
+ zval types
+************
+
+.. code:: c
+
+   #define IS_UNDEF     0 /* A variable that was never written to. */
+   #define IS_NULL      1
+   #define IS_FALSE     2
+   #define IS_TRUE      3
+   #define IS_LONG      4 /* An integer value. */
+   #define IS_DOUBLE    5 /* A floating point value. */
+   #define IS_STRING    6
+   #define IS_ARRAY     7
+   #define IS_OBJECT    8
+   #define IS_RESOURCE  9
+   #define IS_REFERENCE 10
+
+These simple integer constants determine what value is currently stored in a variable. If you are a
+PHP developer, these types should sound fairly familiar. They are pretty much an exact reflection of
+the types you may use in regular PHP code. One small oddity is that ``IS_FALSE`` and ``IS_TRUE`` are
+implemented as separate types, instead of as a ``IS_BOOL`` type.
+
+Some of these types are self-contained, they don't store any auxiliary data. This includes
+``IS_UNDEF``, ``IS_NULL``, ``IS_FALSE`` and ``IS_TRUE``. For the rest of the types, we are going to
+require some additional memory to store the actual value of the variable.
 
 ************
  zend_value
@@ -35,43 +62,24 @@ the variable, and a union for the value itself. Let's look at the value first.
        } ww;
    } zend_value;
 
-A C union is a data type that is big enough to hold the biggest of its members. As such, it can hold
-exactly one of its members at a time. For example, ``zend_value`` may store the ``lval`` member, or
-the ``dval`` member, but never both at the same time. Remembering exactly *which* member is stored
-is our job. That's what the ``zval`` types are for.
+A C union is a data type that may store any one of its members at a time, by being (at least) as big
+as its biggest member. For example, ``zend_value`` may store the ``lval`` member, or the ``dval``
+member, but never both at the same time. However, it doesn't know which member is being stored.
+Remembering this is our job, and that's exactly what the ``IS_*`` constants are for.
 
-If you are a PHP developer, the top members should sound pretty familiar, with the exception of
-``counted``. ``counted`` refers to any of the values that use `reference counting <todo>`__ to
-determine the lifetime of a value. This includes strings, arrays, objects, resources and references.
-All of these will be discussed in their own chapters. You may be thinking that some values are
-missing, most notably ``null`` and ``bool``. These values don't hold any auxiliary data, but consist
-solely of the ``zval`` type.
+The top members of ``zend_value`` mostly mirror the ``IS_*`` constants, with the exception of
+``counted``. ``counted`` polymorphically refers to any `reference counted <todo>`__ value, including
+strings, arrays, objects, resources and references. ``null`` and ``bool`` are missing from
+``zend_value`` because their types are self-contained.
 
-************
- zval types
-************
-
-.. code:: c
-
-   #define IS_UNDEF     0 /* A variable that was never written to. */
-   #define IS_NULL      1
-   #define IS_FALSE     2
-   #define IS_TRUE      3
-   #define IS_LONG      4 /* An integer value. */
-   #define IS_DOUBLE    5 /* A floating point value. */
-   #define IS_STRING    6
-   #define IS_ARRAY     7
-   #define IS_OBJECT    8
-   #define IS_RESOURCE  9
-   #define IS_REFERENCE 10
+The rest of the fields aren't important for now.
 
-These simple integers determine what value is currently stored in ``zend_value``. Together, the
-value and the tag make up the ``zval``, along with some other fields. Note how ``IS_NULL``,
-``IS_FALSE`` and ``IS_TRUE`` are actually ``zval`` types. This explains why they are absent from
-``zend_value``.
+******
+ zval
+******
 
-Finally, here's what the ``zval`` struct actually looks like. This may look intimidating at first.
-Don't worry, we'll go over it step by step.
+Together, the value and the tag make up the ``zval``, along with some other fields. It may look
+intimidating at first. We'll go over it step by step.
 
 .. code:: c
 
@@ -104,27 +112,16 @@ Don't worry, we'll go over it step by step.
        } u2;
    };
 
-``zval.value`` reserves space for the actual variable data, if the type requires any.
-
-``zval.u1`` stores the type of the variable. This refers to the ``IS_*`` constants above. You may be
-wondering why this is a ``union``. In short, this field is used not only for the ``IS_*`` constants,
-but also some other flags. The entire ``type_info`` consists of 4 bytes. ``zval.u1.v.type``, the
-lowest byte, is used for the ``IS_*`` constants. ``zval.u1.v.type_flags`` is used for the
-``IS_TYPE_REFCOUNTED`` and ``IS_TYPE_COLLECTABLE`` flags. They will be discussed within the
-`reference counting <todo>`__ chapter. ``zval.u1.v.u.extra`` (containing the useless ``u`` union) is
-currently only used for the ``IS_STATIC_VAR_UNINITIALIZED`` flag, which is somewhat of a fringe-case
-we won't get into here. So, ``zval.u1.type_info`` and ``zval.u1.v`` are essentially two ways to
-access the same data. The ``ZEND_ENDIAN_LOHI_3`` macro is used to guarantee ordering of bytes across
-big- and little-endian architectures.
-
-If you're familiar with C, you'll know that the compiler likes to add padding to structures with
-"odd" sizes. It does that because the CPU can work with some offsets more efficiently that others.
-Ignoring the ``zval.u2`` field for a second, our struct would be 12 bytes in total, 8 coming from
-``zval.value`` and 4 from ``zval.u1``. A compiler on a 64-bit architecture will generally bump this
-to 16 bytes by adding 4 bytes of useless padding. If this padding is added anyway, we might as well
-make use of it. ``zval.u2`` is often unoccupied, but provides 4 additional bytes to be used in
-various contexts. How exactly the value is used depends on the use case, but it's important to
-remember that it may only be used for one of them at a time.
+``zval.value`` reserves space for the actual variable data, as discussed above.
+
+``zval.u1`` stores the variable type, the given ``IS_*`` constant, along with some other flags. It's
+definition looks a bit complicated. You can think of the entire field as a 4 bit integer, split into
+3 parts. ``v.type`` stores the actual variable type, ``v.type_flags`` is used for some `reference
+counting <todo>`__ flags, and ``v.u.extra`` is pretty much unused.
+
+``zval.u2`` defines some more storage for various contexts that is often unoccupied. It's there
+because the memory would otherwise be wasted due to padding, so we may as well make use of it. We'll
+go over the relevant ones in their corresponding chapters.
 
 ********
  Macros