Работа с аргументами, передаваемыми по ссылке

Если ваша функция принимает передаваемые по ссылке аргументы, которые вы намереваетесь изменять, вы должны предпринять некоторые меры предосторожности.

Мы ещё не говорили, что при указанных обстоятельствах вы не имеете доступа для записи любого параметра функции назначения zval-контейнера, передаваемого (параметр) вам. Конечно, вы можете изменять любой zval-контейнер, который создали внутри вашей функции, но вы обязаны не изменять любые zvals, которые ссылаются на внутренние Zend-данные!

Мы обсудили только так называемый *_ex() API. Вы могли заметить, что API-функции, использованные нами, вызываются zend_get_parameters_ex(), вместо zend_get_parameters(), convert_to_long_ex() вместо convert_to_long(), etc. Функции *_ex() образуют так называемый новый "расширенный/extended" Zend API. Они дают незначительное увеличение скорости по сравнению со старым API, но предназначаются главным образом для предоставления доступа "только-для-чтения".

Поскольку Zend работает внутренне со ссылками, разные переменные могут ссылаться на одно значение. Доступ для записи в zval-контейнер требует, чтобы этот контейнер содержал изолированное значение, то есть значение, на которое нет ссылок из других контейнеров. Если бы на zval-контейнер имелись ссылки из других контейнеров и вы изменили бы zval, на который ссылаются, вы могли бы автоматически изменять содержимое других контейнеров, ссылаясь на данный zval (поскольку они просто указывали бы на изменённое значение и изменяли бы таким образом свои собственные значения).

zend_get_parameters_ex() не отслеживает такую ситуацию, а просто возвращает указатель на желаемые zval-контейнеры, независимо от того, состоят они из ссылок или нет. Соответствующая ему функция в традиционном API, zend_get_parameters(), немедленно проверяет значения по ссылкам. Если он обнаруживает ссылку, он создаёт новый изолированный zval-контейнер; копирует ссылочные данные в это вновь выделенное пространство; затем возвращает указатель на это новое изолированное значение.

Эта акция называется zvalseparation\сепарация zval (или zval separation). Поскольку *_ex() API не выполняет zval separation, он работает быстрее, отменяя за это же время доступ для записи.

Однако для изменения параметров доступ для записи необходим. Zend обрабатывает эту ситуацию специальным способом: При передаче параметра в функцию по ссылке, он выполняет автоматическую zval-сепарацию. Это означает, что всякий раз, когда вызываете функцию вроде этой в PHP, Zend автоматически будет гарантировать, что этот $parameter передаётся как изолированное значение с переводом его в состояние write-safe/безопасной записи:

my_function(&$parameter);

Но это не так в случае в регулярными параметрами! Все другие параметры, которые не передаются по ссылке, находятся в состоянии read-only/только-для-чтения.

Это требует, чтобы вы гарантировали, что вы реально работаете со ссылкой - иначе вы можете получить нежелательный результат. Для проверки передачи параметра по ссылке вы можете использовать макрос PZVAL_IS_REF. Этот макрос принимает zval* и проверяет, является он ссылкой или нет. Примеры даны в Листинге 9.6 и на Рисунке 9.9 (см. на CD-ROM полный исходник).

Рисунок 33-9. Листинг 9.6. Тестирование передачи параметра как ссылки

zval *parameter;

if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", &parameter) == FAILURE)
    return;
}

/* проверить, передан ли параметр по ссылке */
if (!PZVAL_IS_REF(*parameter)) {
{
    zend_error(E_WARNING, "Parameter wasn't passed by reference");
    RETURN_NULL();
}

/* сделать изменения в параметре */
ZVAL_LONG(*parameter, 10);