Programming PHP

Along with this union, each container has a flag that holds the currently active type,
whether it is a reference or not, and the reference count. So the actual pval/zval
struct looks like this:
struct _zval_struct {
zvalue_value value;
zend_uchar type;
zend_uchar is_ref;
zend_ushort refcount;
};
Because this structure could change in future versions of PHP, be sure to use the various
access functions and macros described in the following sections, rather than
directly manipulating the container.
MAKE_STD_ZVAL( )
The most basic of the pval/zval access macros provided by the extension API is the
MAKE_STD_ZVAL( ) macro:
zval *var;
MAKE_STD_ZVAL(var);
This does the following:
• Allocates memory for the structure using emalloc( )
• Sets the container reference count to 1
• Sets the container is_ref flag to 0
At this point, the container has no value—effectively, its value is null. In the “Accessor
Macros” section, we’ll see how to set a container’s value.
SEPARATE_ZVAL( )
Another important macro is SEPARATE_ZVAL( ), used when implementing copy-onwrite
kinds of behavior. This macro creates a separate copy of a zval container only
if the structure to be changed has a reference count greater than 1. A reference count
of 1 means that nothing else has a pointer to this zval, so we can change it directly
and don’t need to copy off a new zval to change.
Assuming a copy needs to be made, SEPARATE_ZVAL( ) decrements the reference count
on the existing zval, allocates a new one, and does a deep copy of whatever value is
stored in the original zval to the fresh copy. It then sets the reference count to 1 and
is_ref to 0, just like MAKE_STD_ZVAL( ).
zval_copy_ctor( )
If you just want to make a deep copy directly and manage your own reference
counts, you can call the zval_copy_ctor( ) function directly.
332 | Chapter 14: Extending PHP
This is the Title of the Book, eMatter Edition
Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved.