May 2007


迟早你会遇到把一个 zval 容器的内容赋给另外一个 zval 容器的情况。不过可别想当然,这事说起来容易做起来可有点难度。因为 zval 容器不但包含了类型信息,而且还有对 Zend 内部数据的一些引用。比如,数组以及对象等依据其大小大都或多或少包含了一些哈希表结构。而我们在将一个 zval 赋给另外一个 zval 时,通常都没有复制这些哈希表本身,复制的只是这些哈希表的引用而已。

为了能够正确复制这些复杂类型的数据,我们可以使用“拷贝构造函数(copy constructor)”来完成这项工作。拷贝构造函数在某些为了可以复制复杂类型数据而支持操作符重载的语言中有着代表性的应用。如果你在这种语言中定义了一个对象,那你就可能想为其重载(Overloading)一下“=”操作符,这个操作符通常用于将右值(操作符右边表达式的值)赋给左值(操作符左边表达式的值)。

“重载”就意味着将给予这个操作符另外一种不同的含义,它通常会把这个操作符跟某个函数调用关联起来。当这个操作符作用在一个对象上时,与之关联的函数就将会被调用,同时该操作符的左值和右值也会作为该函数的参数一并传入。这样,这个函数就可以完成“=”操作符想要完成的事情(一般是某些额外数据的复制)。

这些“额外数据的复制”对 PHP 的 zval 容器来说也是很有必要的。对于数组来说,“额外数据的复制”就是指另外再重建和复制那些与该数组有关的哈希表(因为当初我们复制 zval 时复制的仅仅是这些哈希表的指针)。而对字符串来说,“额外数据的复制”就意味着我们必须重新为字符串值去申请空间。如此类推。

Zend Engine 会调用一个名为 zval_copy_ctor()(在以前的 PHP 版本中这个函数叫做 pval_copy_constructor() )的函数来完成这项工作。

下面这个示例为我们展示了这样一个函数:它接收一个复杂类型的参数,在对其进行一定的修改后把它作为结果返回给 PHP:

zval *parameter;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", ¶meter) == FAILURE) {
    return;
}

// 在这对参数做一定的修改
……

// 返回修改后的容器
*return_value = *parameter;
zval_copy_ctor(return_value);

函数的头一部分没什么可说的,只是一段很平常的接收参数的代码而已。不过在对这个参数进行了某些修改后就变得有趣起来了:先是把 parameter 容器值赋给了(预先定义好的)return_value 容器,然后为了能够真正复制这个容器,我们便调用了拷贝构造函数。这个拷贝构造函数能够直接处理它的参数,处理成功则返回 SUCCESS,否则返回 FAILURE

在这个例子当中如果你忘了调用这个拷贝构造函数,那么 parameterreturn_value 就会分别指向同一个 Zend 内部数据,也就是说返回值 return_value 非法指向了一个数据结构。当你修改了参数 parameter 时这个函数的返回值就可能会受到影响。因此为了创建一个独立的拷贝,我们必须调用这个函数。

在 Zend API 中还有一个与拷贝构造函数相对应的拷贝析构函数:zval_dtor(),它做的工作正好与拷贝构造函数相反。

当 PHP 脚本与扩展互相交换数据时,我们还需要做一件很重要的事情,那就是创建变量。这一小节将会展示如何处理那些 PHP 脚本所支持的变量类型。

概述

要创建一个能够被 PHP 脚本所访问的“外部变量”,我们只需先创建一个 zval 容器,然后对这个 zval 结构进行必要的填充,最后再把它引入到 Zend 的内部符号表中就可以了。而且几乎所有变量的创建基本上都是这几个步骤:

zval *new_variable;

/* 申请并初始化一个新的的 zval 容器 */
MAKE_STD_ZVAL(new_variable);

/* 设置变量的类型和内容,见下 */
/* 将名为 "new_variable_name" 变量引入符号表 */
ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable); 

/* 现在就可以在脚本中用 $new_variable_name 来访问这个变量了 */

宏 MAKE_STD_ZVAL 通过 ALLOC_ZVAL 来申请一个新的 zval 容器的内存空间并调用 INIT_ZVAL(查看 PHP4/5 的源代码可知此处可能为原文笔误,实际上应为 INIT_PZVAL,下同。译注)将其初始化。在当前的 Zend Engine 中,INIT_ZVAL 所负责的初始化工作除了将 zval 容器的引用计数(refcount)置为 1 之外,还会把引用标识也清除(即把 is_ref  也置为 0)。而且在以后的 Zend Engine 中还可能会继续扩展这个 INIT_ZVAL 宏操作,因此我们推荐您使用 MAKE_STD_ZVAL 而非简单使用一个 ALLOC_ZVAL 来完成一个变量的创建工作。当然,如果您是想优化一下速度(或者是不想明确地初始化这个 zval 容器),那还是可以只用 ALLOC_ZVAL 来搞定的。不过我们并不推荐这么做,因为这将不能保证数据的完整性。

ZEND_SET_SYMBOL 宏负责将我们新建的变量引入 Zend 内部的符号表。这个宏会首先检查一下这个变量是否已经存在于符号表中,如果已经存在则将其转换为一个引用变量(同时会自动销毁原有的 zval 容器)。事实上这个方法经常用在某些速度要求并不苛刻但希望能少用一些内存的情况下。

您可能注意到了 ZEND_SET_SYMBOL 是通过宏 EG 来访问 Zend 执行器(executor)的全局结构的。特别的,如果你使用的是 EG(active_symbol_table),那你就可以访问到当前的活动符号表,从而可以处理一些全局或局部变量。其中局部变量可能会依不同的函数而有所不同。

当然,要是你很在意程序的运行速度并且不在乎那一点点内存的话,那你可以跳过对相同名字变量存在性的检查而直接使用 zend_hash_update() 函数强行将这个名字的变量插入符号表。

zval *new_variable;

/* 申请并初始化一个新的的 zval 容器 */
MAKE_STD_ZVAL(new_variable);

/* 设置变量的类型和内容,见下 */

/* 将名为 "new_variable_name" 变量引入符号表 */
zend_hash_update(
    EG(active_symbol_table),
    "new_variable_name",
    strlen("new_variable_name") + 1,
    &new_variable,
    sizeof(zval *),
    NULL
);

实际上这段代码也是很多扩展使用的标准方法。

上面这段代码所产生的变量是局部变量,作用范围跟调用函数的上下文相关。如果你想创建一个全局变量那也很简单,方法还是老方法,只需换个符号表就可以了。

zval *new_variable;
/* 申请并初始化一个新的的 zval 容器 */
MAKE_STD_ZVAL(new_variable);

/* 设置变量的类型和内容,见下 */

/* 将名为 "new_variable_name" 变量引入全局符号表 */
ZEND_SET_SYMBOL(&EG(symbol_table), "new_variable_name", new_variable);

注意,现在宏 ZEND_SET_SYMBOL 使用的符号表是全局符号表 EG(symbol_table)。另外,active_symbol_table 是一个指针,而 symbol_table 却不是。这就是我们为什么分别使用 EG(active_symbol_table)&EG(symbol_table) 的原因 - ZEND_SET_SYMBOL 需要一个指针作为其参数。

当然,你同样也可以强行更新这个符号表:

zval *new_variable;

/* 申请并初始化一个新的的 zval 容器 */
MAKE_STD_ZVAL(new_variable);

/* 设置变量的类型和内容,见下 */

/* 将名为 "new_variable_name" 变量引入全局符号表 */
zend_hash_update(
    &EG(symbol_table),
    "new_variable_name",
    strlen("new_variable_name") + 1,
    &new_variable,
    sizeof(zval *),
    NULL
); 

例 3.9 “创建不同作用域的变量”向我们展示了创建一个局部变量(local_variable)和一个全局变量(global_variable)的过程。

注意:你可能会发现在 PHP 函数里似乎还不能直接访问这个全局变量(global_variable),因为你在使用前还必须使用 global $global_variable; 声明一下。

例3.9 创建不同作用域的变量

ZEND_FUNCTION(variable_creation)
{
   zval *new_var1, *new_var2;
   MAKE_STD_ZVAL(new_var1);
   MAKE_STD_ZVAL(new_var2);
   ZVAL_LONG(new_var1, 10);
   ZVAL_LONG(new_var2, 5);
   ZEND_SET_SYMBOL(EG(active_symbol_table), "local_variable", new_var1);
   ZEND_SET_SYMBOL(&EG(symbol_table), "global_variable", new_var2);
   RETURN_NULL();
}

长整型(整数)

现在让我们以长整型变量起点,了解一下如何为一个变量赋值。PHP 中的整数全部是长整型,其值的存储方法也是非常简单的。看一下我们前面讨论过的 zval.value 容器的结构你就会明白,所有的长整型数据都是直接保存在这个联合中的 lval 字段,相应的数据类型(type 字段)为 IS_LONG(见例3.10 “长整型变量的创建”)。

例3.10 长整型变量的创建

zval *new_long;
MAKE_STD_ZVAL(new_long);
new_long->type = IS_LONG;
new_long->value.lval = 10;

或者你也可以直接使用 ZVAL_LONG 宏:

zval *new_long;
MAKE_STD_ZVAL(new_long);
ZVAL_LONG(new_long, 10);

双精度型(浮点数)

PHP 中的浮点数都是双精度型,存储方法和整型差不多,也很简单。它的值是直接放在联合中的 dval 字段,对应数据类型为 IS_DOUBLE

zval *new_double;
MAKE_STD_ZVAL(new_double);
new_double->type = IS_DOUBLE;
new_double->value.dval = 3.45;

同样你也可以直接使用宏 ZVAL_DOUBLE

zval *new_double;
MAKE_STD_ZVAL(new_double);
ZVAL_DOUBLE(new_double, 3.45);

字符串

字符串的存储可能会稍费点事。字符串的值是保存在 zval.value 容器中的 str 结构里面,相应的数据类型为 IS_STRING。不过需要注意的是,前面我们已经提到过,所有与 Zend 内部数据结构相关的字符串都必须使用 Zend 自己的内存管理函数来申请空间。这样一来,就不能使用那些静态字符串(因为这种字符串的内存空间是编译器预先分配的)或通过标准函数(比如 malloc() 等函数)来申请空间的字符串。

zval *new_string;
char *string_contents = "This is a new string variable";

MAKE_STD_ZVAL(new_string);

new_string->type = IS_STRING;
new_string->value.str.len = strlen(string_contents);
new_string->value.str.val = estrdup(string_contents);

请注意,在这我们使用了 estrdup() 函数。当然我们仍可直接使用一个预定义宏 ZVAL_STRING 来完成这项工作:

zval *new_string;
char *string_contents = "This is a new string variable";

MAKE_STD_ZVAL(new_string);

ZVAL_STRING(new_string, string_contents, 1);

ZVAL_STRING 宏的第三个参数指明了该字符串是否需要被复制(使用 estrdup() 函数)。值为 1 将导致该字符串被复制,为 0 时则仅仅是简单地将其指向该变量的值容器(即字符串地址,译注)。这项特性将会在你仅仅需要创建一个变量并将其指向一个已经由 Zend 内部数据内存时变得很有用。

如果你想在某一位置截取该字符串或已经知道了这个字符串的长度,那么可以使用宏 ZVAL_STRINGL(zval, string, length, duplicate) 来完成这项工作。这个函数会额外需要一个表明该字符串长度地参数。这个宏不但速度上要比 ZVAL_STRING 快,而且还是二进制安全的。

如果想创建一个空字符串,那么将其长度置 0 并且把 empty_string 作为字符串的内容即可:

new_string->type = IS_STRING;
new_string->value.str.len = 0;
new_string->value.str.val = empty_string;

当然,我们也专门为您准备了一个相应的宏 ZVAL_EMPTY_STRING 来搞定这个步骤:

MAKE_STD_ZVAL(new_string);
ZVAL_EMPTY_STRING(new_string);

布尔类型

布尔类型变量的创建跟长整型差不多,只是数据类型为 IS_BOOL,并且字段 lval 所允许的值只能为 0 和 1:

zval *new_bool;
MAKE_STD_ZVAL(new_bool);
new_bool->type = IS_BOOL;
new_bool->value.lval = 1;

也可以使用宏 ZVAL_BOOL (需要另外指定一个值)来完成这件事情,或者干脆直接使用ZVAL_TRUEZVAL_FALSE 直接将其值设定为 TRUEFALSE

数组

数组在 Zend 内部是用哈希表(HashTable)来存储的,这个哈希表可以使用一系列的 zend_hash_*() 函数来访问。因此我们在创建一个数组时必须先创建一个哈希表,然后再将其保存在 zval.value 容器的 ht 字段中。

不过针对数组的创建我们现在另有一套非常方便 API 可供使用。为了创建一个数组,我们可先调用一下 array_init() 函数:

zval *new_array;
MAKE_STD_ZVAL(new_array);
array_init(new_array); // array_init() 函数总是返回 SUCCESS

要给数组增加一个元素,根据实际需要,我们有 N 个函数可供调用。“表3.8 用于关联数组的 API”、“表3.9 用于索引数组的 API 第一部分”和“表3.10 用于索引数组的 API 第二部分”有这些函数的说明。所有这些函数在调用成功时返回 SUCCESS,在调用失败时返回 FAILURE。

表3.8 用于关联数组的 API

函数 说明
add_assoc_long(zval *array, char *key, long n); 添加一个长整型元素。
add_assoc_unset(zval *array, char *key); 添加一个 unset 元素。
add_assoc_bool(zval *array, char *key, int b); 添加一个布尔值。
add_assoc_resource(zval *array, char *key, int r); 添加一个资源。
add_assoc_double(zval *array, char *key, double d); 添加一个浮点值。
add_assoc_string(zval *array, char *key, char *str, int duplicate); 添加一个字符串。duplicate 用于表明这个字符串是否要被复制到 Zend 的内部内存。
add_assoc_stringl(zval *array, char *key, char *str, uint length, int duplicate); 添加一个指定长度的字符串。其余跟add_assoc_string () 相同。
add_assoc_zval(zval *array, char *key, zval *value); 添加一个 zval 结构。 这在添加另外一个数组、对象或流等数据时会很有用。

表3.9 用于索引数组的 API 第一部分

函数 说明
add_index_long(zval *array, uint idx, long n); 添加一个长整型元素。
add_index_unset(zval *array, uint idx); 添加一个 unset 元素。
add_index_bool(zval *array, uint idx, int b); 添加一个布尔值。
add_index_resource(zval *array, uint idx, int r); 添加一个资源。
add_index_double(zval *array, uint idx, double d); 添加一个浮点值。
add_index_string(zval *array, uint idx, char *str, int duplicate); 添加一个字符串。duplicate 用于表明这个字符串是否要被复制到 Zend 的内部内存。
add_index_stringl(zval *array, uint idx, char *str, uint length, int duplicate); 添加一个指定长度的字符串。其余跟add_index_string () 相同。
add_index_zval(zval *array, uint idx, zval *value); 添加一个 zval 结构。 这在添加另外一个数组、对象或流等数据时会很有用。

表3.10 用于索引数组的 API 第二部分

函数 说明
add_next_index_long(zval *array, long n); 添加一个长整型元素。
add_next_index_unset(zval *array); 添加一个 unset 元素。
add_next_index_bool(zval *array, int b); 添加一个布尔值。
add_next_index_resource(zval *array, int r); 添加一个资源。
add_next_index_double(zval *array, double d); 添加一个浮点值。
add_next_index_string(zval *array, char *str, int duplicate); 添加一个字符串。duplicate 用于表明这个字符串是否要被复制到 Zend 的内部内存。
add_next_index_stringl(zval *array, char *str, uint length, int duplicate); 添加一个指定长度的字符串。其余跟add_next_index_string () 相同。
add_next_index_zval(zval *array, zval *value); 添加一个 zval 结构。 这在添加另外一个数组、对象或流等数据时会很有用。

所有这些函数都是对 Zend 内部 hash API 的一种友好抽象。因此,若你愿意,你大可直接使用那些 hash API 进行操作。比方说,假如你已经有了一个 zval 容器并想把它插入到一个数组,那么你就可以直接使用 zend_hash_update() 来把它添加到一个关联数组(例3.11 给关联数组添加一个元素)或索引数组(例3.12 给索引数组添加一个元素)。

例3.11 给关联数组添加一个元素

zval *new_array, *new_element;
char *key = "element_key";
MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);
array_init(new_array);
ZVAL_LONG(new_element, 10);
if(zend_hash_update(new_array->value.ht, key, strlen(key) + 1, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
    // do error handling here
} 

例3.12 给索引数组添加一个元素

zval *new_array, *new_element;
int key = 2;
MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);
array_init(new_array);
ZVAL_LONG(new_element, 10);
if(zend_hash_index_update(new_array->value.ht, key, (void *)&new_element, sizeof(zval *), NULL) == FAILURE)
{
    // do error handling here
} 

如果还想模拟下 add_next_index_*() ,那可以这么做:

zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL)

注意:如果要从函数里面返回一个数组,那就必须首先对预定义变量 return_value (return_value 是我们导出函数中的一个预定义参数,用来存储返回值)使用一下 array_init() 函数。不过倒不必对其使用 MAKE_STD_ZVAL 。

提示:为了避免一遍又一遍地书写 new_array->value.ht,我们可以用 HASH_OF(new_array) 来代替。而且出于兼容性和风格上的考虑,我们也推荐您这么做。

对象

既然对象可以被转换成数组(反之亦然),那么你可能已经猜到了两者应该具有很多相似之处。实际上,对象就是使用类似的函数进行操作的,所不同的是创建它们时所用的 API。

我们可以调用 object_init() 函数来初始化一个对象:

zval *new_object;
MAKE_STD_ZVAL(new_object);
if(object_init(new_object) != SUCCESS)
{
    // do error handling here
}

可以使用“表3.11 用于创建对象的 API”来给对象添加一些成员。

表3.11 用于创建对象的 API

函数 说明
add_property_long(zval *object, char *key, long l); 添加一个长整型类型的属性值。
add_property_unset(zval *object, char *key); 添加一个 unset 类型的属性值。
add_property_bool(zval *object, char *key, int b); 添加一个布尔类型的属性值。
add_property_resource(zval *object, char *key, long r); 添加一个资源类型的属性值。
add_property_double(zval *object, char *key, double d); 添加一个浮点类型的属性值。
add_property_string(zval *object, char *key, char *str, int duplicate); 添加一个字符串类型的属性值。
add_property_stringl(zval *object, char *key, char *str, uint length, int duplicate); 添加一个指定长度的字符串类型的属性值,速度要比 add_property_string() 函数快,而且是二进制安全的。
add_property_zval(zval *obect, char *key, zval *container); 添加一个 zval 结构的属性值。 这在添加另外一个数组、对象等数据时会很有用。

资源

资源是 PHP 中一种比较特殊的数据类型。“资源”这个词其实并不特指某些特殊类型的数据,事实上,它指的是一种可以维护任何类型数据信息方法的抽象。所有的资源均保存在一个 Zend 内部的资源列表当中。列表中的每份资源都有一个指向可以表明其种类的类型定义的指针。Zend 在内部统一管理所有对资源的引用。直接访问一个资源是不大可能的,你只能通过提供的 API 来对其进行操作。某个资源一旦失去引用,那就会触发调用相应的析构函数。

举例来说,数据库连接和文件描述符就是一种资源。MySQL 模块中就有其“标准”实现。当然其他模块(比如 Oracle 模块)也都用到了资源。

注意:

实际上,一个资源可以指向函数中任何一种你所感兴趣的数据(比如指向一个结构等等)。并且用户也只能通过某个资源变量来将资源信息传递给相应的函数。

要想创建一个资源你必须先注册一个这个资源的析构函数。这是因为Zend 需要了解当你把某些数据存到一个资源里后,如果不再需要这份资源时该如何将其释放。这个析构函数会在释放资源(无论是手工释放还是自动释放)时被 Zend 依次调用。析构函数注册后,Zend 会返回一个此种资源类型句柄。这个句柄会在以后任何访问此种类型的资源的时候被用到,而且这个句柄绝大部分时间都保存在扩展的全局变量里面。这里你不需要担心线程安全方面的问题,因为你只是需要在模块初始化注册一次就行了。

下面是这个用于注册资源析构函数的 Zend 函数定义:

ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, char *type_name, int module_number);

你或许已经注意到了,在该函数中我们需要提供两种不同的资源析构函数:一种是普通资源的析构函数句柄,一种是持久化资源的析构函数句柄。持久化资源一般用于诸如数据库连接等这类情况。在注册资源时,这两个析构函数至少得提供一个,另外一个析构函数可简单地设为 NULL。

zend_register_list_destructors_ex() 接受以下几个参数:

ld 普通资源的析构函数。
ld 持久化资源的析构函数。
type_name 为你的资源指定一个名称。在 PHP 内部为某个资源类型起个名字这是个好习惯(当然名字不能重复)。用户调用 var_dump($resource) 时就可取得该资源的名称。
module_number 这个参数在你模块的 PHP_MINIT_FUNCTION 函数中会自动定义,因此你大可将其忽略。

返回值是表示该资源类型的具有唯一性的整数标识符,即资源类型句柄

资源(不论是不是持久化资源)的析构函数都必须具有以下的函数原型:

void resource_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC);

参数 rsrc 指向一个 zend_rsrc_list_entry 结构:

typedef struct _zend_rsrc_list_entry {
    void *ptr;
    int type;
    int refcount;
} zend_rsrc_list_entry;

成员 void *ptr 才真正指向你的资源。

现在我们就知道该怎么开始了。我们先定义一个将要注册到 Zend 内部的资源类型 my_resource,这个类型的结构很简单,只有两个整数成员:

typedef struct {
    int resource_link;
    int resource_type;
} my_resource;  

接着我们再定义一下这种资源的析构函数。这个析构函数大致上是以下这个样子:

void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {
    // 先将无类型指针转换为我们的资源类型指针
    my_resource *my_rsrc = (my_resource *) rsrc->ptr;

    // 现在我们就可以随意处理这些资源了:像关闭文件、释放内存等等。
    // 当然也不要忘了释放资源本身所占用的内存! 
    do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
}

注意:

有一个很重要的事情必须要提一下:如果你的资源是一个比较复杂的结构,比如包含有你在运行时所申请内存的指针等,那你就必须在释放资源本身前释放它们!

OK。现在我们定义了

  1. 我们的资源是什么样子;
  2. 我们资源的析构函数是什么样子。

那么,我们还需要做哪些工作呢?我们还需要:

  1. 创建一个在整个扩展范围内有效的全局变量用于保存资源类型句柄,这样就可以在每个需要它的函数中都能访问到它;
  2. 给我们的资源类型定义一个名称;
  3. 完成前面定义的资源析构函数;
  4. 最后注册这个析构函数。
    // 在你扩展的某个地方定义一个表示资源类型的变量
    static int le_myresource;

    // 给我们的资源起个名字是个很不错的习惯
    #define le_myresource_name  "My type of resource" 

   [...]

    // 现在完成我们资源的析构函数
    void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {
       my_resource *my_rsrc = (my_resource *) rsrc->ptr;
       do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
    }

    [...] 
    PHP_MINIT_FUNCTION(my_extension) {
        // 注意 'module_number' 已经在 PHP_MINIT_FUNCTION() 函数中被定义过了
        le_myresource = zend_register_list_destructors_ex(my_destruction_handler, NULL, le_myresource_name, module_number);
        
        // 然后你可以在这里注册一些附加资源、初始化全局变量、常量等等。
   }  

注册完这种资源的析构函数后,要真正注册一个资源(实例),我们可以使用 zend_register_resource() 函数或使用 ZEND_REGISTER_RESOURE() 宏。这两个的定义可以在 zend_list.h 中找到。尽管两者的参数定义都是一一对应的,但使用宏通常可以得到更好的前向兼容性:

int ZEND_REGISTER_RESOURCE(zval *rsrc_result, void *rsrc_pointer, int rsrc_type);  
rsrc_result 这是一个初始化过 zval * 容器。
rsrc_pointer 指向所保存的资源。
rsrc_type 这个参数就是你在注册函数析构函数时返回的资源类型句柄。对上面的代码来说就是le_myresource le_myresource。

返回值就是表示这个资源(实例)的具有唯一性的整数。

那么在我们注册这个资源(实例)时究竟发生了什么事呢?函数会从 Zend 内部某个列表取得一个空闲空间,然后将资源指针及类型保存到这个空间。最后这个空闲空间的索引被简单地保存在给定的 zval * 容器里面:

rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type);
if (rsrc_result) {
    rsrc_result->value.lval = rsrc_id;
    rsrc_result->type = IS_RESOURCE;
}
return rsrc_id;  

返回值 rsrc_id 就唯一性地标识了我们新注册得到的那个资源。你可以使用宏RETURN_RESOURE 来将其返回给用户:

RETURN_RESOURCE(rsrc_id)

注意:

如果你想立刻把这个资源返回给用户,那你就应该把 return_value 作为那个 zval * 容器。这也是我们推荐的一种编程实践。

Zend 引擎从现在就会开始跟踪所有对这个资源的引用。一旦对这个资源的引用全都不存在了,那么你在前面为这个资源所注册的析构函数就会被调用。这样做的好处就是你不用担心会在你的模块里面引入内存泄漏-你只需要把你调用脚本中所有需要分配的内存都注册成资源即可。这样一来,一旦脚本认为不再需要它们的时候,Zend 就会找到它们然后再通知你(这就是 callback,译注)。

现在用户已经通过在某处传入到你函数的参数拿到了他的资源。zval * 容器中的 value.lval 包含了你资源的标识符,然后他就可以宏 ZEND_FETCH_RESOURCE 来获取资源了:

ZEND_FETCH_RESOURCE(rsrc, rsrc_type, rsrc_id, default_rsrc_id, resource_type_name, resource_type)

rsrc 这个指针将指向你前面已经声明过的资源。
rsrc_type 这个参数用以表明你你想要把前面参数的那个指针转换为何种类型。比如 myresource * 等等。
rsrc_id 这个是用户传进你函数的那个 zval *container 的地址。 假如给出的是 zval *z_resource ,那么此处就应该是 &z_resource
default_rsrc_id 这个参数表明假如没有取到资源时默认指定的资源标识符。通常为 -1。
resource_type_name 所请求的资源类型资源类型名称。当不能找到资源时,就用这个字符串去填充系统由于维护而抛出的错误信息。
resource_type 这个可以取回在注册资源析构函数时返回的资源类型。在本例就是 le_myresource

这个宏没有返回值。这对开发人员可能会方便了点。不过还是要注意添加 TSRM 参数和确认一下是否取回了资源。如果在接收资源时出现了问题,那它就会抛出一个警告信息并且会立刻从当前函数返回,其返回值为 NULL。

如果想从列表强行删除一个资源,可以使用 zend_list_delete() 函数。当然也可以强行增加引用计数,如果你知道你正在创建一个指向已分配内存资源的引用(比如说你可能想重用一个默认的数据库连接)。对于这种情况你可以使用函数 zend_list_addref() 。想要查找一个已分配内存的资源,请使用 zend_list_find() 函数。关于这些操作的完整 API 请参见 zend_list.h

自动创建全局变量的宏

作为我们早期所谈论的一些宏的补充,还有一些宏可以让我们很方便的创建全局变量。了解了它们,我们在引入一些全局标识时就会感觉很爽,不过这个习惯可能会不太好。在“表3.12 创建全局变量的宏”中描述了完成这些任务所用到的正确的宏。它们不需要申请任何 zval 容器,你只需简单地提供一个变量名和其值即可。

表3.12 创建全局变量的宏

说明
SET_VAR_STRING(name, value) 新建一个字符串变量。
SET_VAR_STRINGL(name, value, length) 新建一个指定长度的字符串变量。这个宏要比 SET_VAR_STRING 快而且还是二进制安全的。
SET_VAR_LONG(name, value) 新建一个长整型变量。
SET_VAR_DOUBLE(name, value) 新建一个双精度变量。

创建常量

Zend 支持创建真正的常量。访问常量时不需要 $ 前缀,而且常量是全局有效的。比如 TRUEFALSE 这两个常量。

要想创建一个常量,你可以使用“表3.13 创建常量的宏”中所列举的宏来完成这项工作。所有的宏在创建常量时都必须指定一个名称和值。

你还可以为常量指定一个特别的标识:

  • CONST_CS – 这个常量的名称是大小写敏感的;
  • CONST_PERSISTENT – 这个常量是持久化的。换句话说,当携带这个常量的进程关闭时这个常量在剩下的请求中还依然有效,并不会被“遗忘”。

可以使用二进制的“或(OR)”操作来使用其中的一个或两个标识:

// 注册一个长整型常量
REGISTER_LONG_CONSTANT("NEW_MEANINGFUL_CONSTANT", 324, CONST_CS | CONST_PERSISTENT);

我们提供有两种不同类型的宏,分别是 REGISTER_*_CONSTANTREGISTER_MAIN_*_CONSTANT。第一种类型在创建常量时只会绑定到当前模块。一旦注册这个模块的常量从内存中卸载,那么这个常量也就会随即消逝。第二种类型创建的变量将会独立于该模块,始终保存在符号表中。

表3.13 创建常量的宏

说明
REGISTER_LONG_CONSTANT(name, value, flags) REGISTER_MAIN_LONG_CONSTANT(name, value, flags) 新建一个长整型常量。
REGISTER_DOUBLE_CONSTANT(name, value, flags) REGISTER_MAIN_DOUBLE_CONSTANT(name, value, flags) 新建一个双精度型常量。
REGISTER_STRING_CONSTANT(name, value, flags) REGISTER_MAIN_STRING_CONSTANT(name, value, flags) 新建一个字符串常量。给定的字符串的空间必须在Zend 内部内存。
REGISTER_STRINGL_CONSTANT(name, value, length, flags) REGISTER_MAIN_STRINGL_CONSTANT(name, value, length, flags) 新建一个指定长度的字符串常量。同样,这个给定的字符串的空间也必须在Zend 内部内存。

算起来这个站点都快有三个月打不开了。不过还好,在一些朋友的帮助下现在似乎是没什么大问题了。

尽管在这个 Blog 上有三个月的空白,但在实际生活中却并非如此。相反,这三个月经过的事情貌似比上一年加起来还多。当然,过去的已经过去,新的生活才刚刚开始~

本年度剩余时间的打算:

  1. 完善一下现有的 PHP 反编译器,完成难度 4;
  2. 写一款较为完善的 PHP 加密工具,完成难度 5;
  3. 使用 Delphi 写一款 PHP 的 IDE,完成难度 7;
  4. 找一份合适的工作,完成难度 8;
  5. 找一个合适的MM,完成难度 10。:(

« Previous Page

'