php/REFCOUNTING.md

# Refcounting Tips

One of the trickiest parts of the C extension for PHP is getting the refcounting
right.  These are some notes about the basics of what you should know,
especially if you're not super familiar with PHP's C API.

These notes cover the same general material as [the Memory Management chapter of
the PHP internal's
book](https://www.phpinternalsbook.com/php7/zvals/memory_management.html), but
calls out some points that were not immediately clear to me.

##  Zvals

In the PHP C API, the `zval` type is roughly analogous to a variable in PHP, eg:

```php
    // Think of $a as a "zval".
    $a = [];
```

The equivalent PHP C code would be:

```c
    zval a;
    ZVAL_NEW_ARR(&a);  // Allocates and assigns a new array.
```

PHP is reference counted, so each variable -- and thus each zval -- will have a
reference on whatever it points to (unless its holding a data type that isn't
refcounted at all, like numbers). Since the zval owns a reference, it must be
explicitly destroyed in order to release this reference.

```c
    zval a;
    ZVAL_NEW_ARR(&a);

    // The destructor for a zval, this must be called or the ref will be leaked.
    zval_ptr_dtor(&a);
```

Whenever you see a `zval`, you can assume it owns a ref (or is storing a
non-refcounted type). If you see a `zval*`, which is also quite common, then
this is *pointing to* something that owns a ref, but it does not own a ref
itself.

The [`ZVAL_*` family of
macros](https://github.com/php/php-src/blob/4030a00e8b6453aff929362bf9b25c193f72c94a/Zend/zend_types.h#L883-L1109)
initializes a `zval` from a specific value type.  A few examples:

* `ZVAL_NULL(&zv)`: initializes the value to `null`
* `ZVAL_LONG(&zv, 5)`: initializes a `zend_long` (integer) value
* `ZVAL_ARR(&zv, arr)`: initializes a `zend_array*` value (refcounted)
* `ZVAL_OBJ(&zv, obj)`: initializes a `zend_object*` value (refcounted)

Note that all of our custom objects (messages, repeated fields, descriptors,
etc) are `zend_object*`.

The variants that initialize from a refcounted type do *not* increase the
refcount. This makes them suitable for initializing from a newly-created object:

```c
    zval zv;
    ZVAL_OBJ(&zv, CreateObject());
```

Once in a while, we want to initialize a `zval` while also increasing the
reference count. For this we can use `ZVAL_OBJ_COPY()`:

```c
zend_object *some_global;

void GetGlobal(zval *zv) {
    // We want to create a new ref to an existing object.
    ZVAL_OBJ_COPY(zv, some_global);
}
```

## Transferring references

A `zval`'s ref must be released at some point. While `zval_ptr_dtor()` is the
simplest way of releasing a ref, it is not the most common (at least in our code
base). More often, we are returning the `zval` back to PHP from C.

```c
    zval zv;
    InitializeOurZval(&zv);
    // Returns the value of zv to the caller and donates our ref.
    RETURN_COPY_VALUE(&zv);
```

The `RETURN_COPY_VALUE()` macro (standard in PHP 8.x, and polyfilled in earlier
versions) is the most common way we return a value back to PHP, because it
donates our `zval`'s refcount to the caller, and thus saves us from needing to
destroy our `zval` explicitly. This is ideal when we have a full `zval` to
return.

Once in a while we have a `zval*` to return instead. For example when we parse
parameters to our function and ask for a `zval`, PHP will give us pointers to
the existing `zval` structures instead of creating new ones.

```c
    zval *val;
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "z", &val) == FAILURE) {
      return;
    }
    // Returns a copy of this zval, adding a ref in the process.
    RETURN_COPY(val);
```

When we use `RETURN_COPY`, the refcount is increased; this is perfect for
returning a `zval*` when we do not own a ref on it.