PHP源码分析-HashTable API

一、创建HashTable

int zend_hash_init(
	HashTable *ht,//指向一个HashTable
	uint nSize,//nSize是指这个HashTable可以拥有的元素的最大数量。在我们添加新的元素时，这个值会根据情况决定是否自动增长，这个值永远都是2的次方，如果你给它的值不是一个2的次方
			//的形式，那它将自动调整成大于它的最小的2的次方值。它的计算方法就像这样：nSize = pow(2, ceil(log(nSize, 2)))。(HashTable能够包含任意数量的元素，这个值只是为了提前申请好内存，提高性
			//能，省的不停的进行rehash操作)
	hash_func_t pHashFunction,//pHashFunction是早期的参数，为向前兼容所以没有去掉。直接赋值NULL即可。
	dtor_func_t pDestructor,//一个回调函数，当我们删除或者修改HashTable中其中一个元素时候便会调用，它的函数原型必须是这样的：void method_name(void *pElement)，一般使用宏ZVAL_PTR_DTOR即可。
	zend_bool persistent//值为0或1，如果是1那么这个HashTable将永远存在于内存中，而不会在RSHUTDOWN阶段自动被注销掉。此时第一个参数ht所指向的地址必须是通过pemalloc()函数申请的。
);

注：
#define ZVAL_PTR_DTOR (void (*)(void *)) zval_ptr_dtor_wrapper

删除元素，回调析构该元素。

二、添加

int zend_hash_add(
	HashTable *ht,		//待操作的ht
	char *arKey,			//索引，如"my_key"
	uint nKeyLen,		//字符串索引的长度，如6
	void **pData,		//要插入的数据，注意它是void **类型的。
	uint nDataSize,		//例如，存放zval类型变量，那么nDataSize=sizeof(zval*)
	void *pDest			//如果操作成功，则pDest=*pData;
);

int zend_hash_next_index_insert(
	HashTable *ht,	//待操作的ht
	void *pData,	//要插入的数据
	uint nDataSize,
	void **pDest
);

三、更新

int zend_hash_update(
	HashTable *ht,
	char *arKey,	//索引字符串
	uint nKeyLen,	//索引字符串长度
	void *pData,
	uint nDataSize,
	void **pDest
);

int zend_hash_index_update(
	HashTable *ht,
	ulong h,
	void *pData,
	uint nDataSize,
	void **pDest
);

四、查找

int zend_hash_find(
	HashTable *ht,
	char *arKey, 	//索引字符串
	uint nKeyLength,	//索引字符串长度
	void **pData	//找到元素，则将元素指向pData
);

int zend_hash_index_find(
	HashTable *ht,
	ulong h, 		//数字索引
	void **pData	//找到元素，则将元素指向pData
);

五、检测

int zend_hash_exists(
	HashTable *ht, 
	char *arKey, 
	uint nKeyLen
);

int zend_hash_index_exists(
	HashTable *ht, 
	ulong h
);

这两个函数返回SUCCESS或者FAILURE，分别代表着是否存在

六、加速

ulong zend_get_hash_value(char *arKey, uint nKeyLen);//返回索引的hash值
通过使用zend_get_hash_value函数得到索引hash值，之后对hashTable进行添加、修改等操作使用quick系列函数可以避免重复计算字符串的hash值，达到加速加速的目的。

int zend_hash_quick_add(
	HashTable *ht,
	char *arKey,
	uint nKeyLen,
	ulong hashval,	//zend_get_hash_value函数得到的hash值
	void *pData,
	uint nDataSize,
	void **pDest
);

int zend_hash_quick_update(
	HashTable *ht,
	char *arKey,
	uint nKeyLen,
	ulong hashval,
	void *pData,
	uint nDataSize,
	void **pDest
);

int zend_hash_quick_find(
	HashTable *ht,
	char *arKey,
	uint nKeyLen,
	ulong hashval,
	void **pData
);

int zend_hash_quick_exists(
	HashTable *ht,
	char *arKey,
	uint nKeyLen,
	ulong hashval
);

七、数组之间的复制与合并

void zend_hash_copy(
	HashTable *target,	//*source中的所有元素都会通过pCopyConstructor函数Copy到*target中去
	HashTable *source,	//target中原有的与source中索引位置的数据会被替换掉，而其它的元素则会被保留，原封不动。
	copy_ctor_func_t pCopyConstructor,	
	void *tmp,//tmp参数是为了兼容PHP4.0.3以前版本的，现在赋值为NULL即可。
	uint size	//size参数代表每个元素的大小，对于PHP语言中的数组来说，这里的便是sizeof(zval*)了。
);

void zend_hash_merge(
	HashTable *target,
	HashTable *source,
	copy_ctor_func_t pCopyConstructor,
	void *tmp,
	uint size,
	int overwrite
);

zend_hash_merge()与zend_hash_copy唯一的不同便是多了个int类型的overwrite参数，当其值非0的时候，两个函数的工作是完全一样的；如果overwrite参数为0，则zend_hash_merge函数就不会对target中已有索引的值进行替换了。

void zend_hash_merge_ex(
	HashTable *target,
	HashTable *source,
	copy_ctor_func_t pCopyConstructor, 
	uint size,
	merge_checker_func_t pMergeSource,
	void *pParam
);

zend_hash_merge_ex函数又繁琐了些，与zend_hash_copy相比，其多了两个参数，多出来的pMergeSoure回调函数允许我们选择性的进行merge，而不是全都merge。

八、遍历

PHP中数组的本质是HashTable，可以使用foreach来遍历PHP中的数组。在内核中则是使用zend_hash_apply函数。
zend_hash_apply接收一个回调函数，并将HashTable的每一个元素都传递给回调函数。这里的回调函数相当于PHP中的foreach循环主体。

回调函数的返回值有一个共同的约定：
ZEND_HASH_APPLY_KEEP		结束当前请求，进入下一个循环。与PHP语言forech语句中的一次循环执行完毕或者遇到	
							continue关键字的作用一样。
ZEND_HASH_APPLY_STOP		跳出，与PHP语言forech语句中的break关键字的作用一样。
ZEND_HASH_APPLY_REMOVE		删除当前的元素，然后继续处理下一个。相当于在PHP语言中：unset($foo
							[$key]);continue;

1、无索引遍历
typedef int (*apply_func_t)(void *pDest TSRMLS_DC);
void zend_hash_apply(HashTable *ht,apply_func_t apply_func TSRMLS_DC);


看看PHP语言中的forech循环。

<?php
function foreach_test($arr){
	foreach($arr as $val) {
	    echo "The value is: $val\n";
	}
}
?>

在内核中实现函数foreach_test。

//zend_hash_apply回调函数，相当于PHP中的foreach主体
int php_foreach_body(zval **zval TSRMLS_DC){
	zval tmpcopy = **zval;		//重新copy一个zval，防止破坏原数据
	zval_copy_ctor(&tmpcopy);

	INIT_PZVAL(&tmpcopy);		//初始化refcount__gc=1, is_ref__gc=0
	convert_to_string(&tmpcopy);	 //转换为字符串

	php_printf("The value is:");
	PHPWRITE(Z_STRVAL(tmpcopy), Z_STRLEN(tmpcopy));
	php_printf("\n");

	zval_dtor(&tmpcopy);
	return ZEND_HASH_APPLY_KEEP;
}

PHP_FUNCTION(foreach_test){
	zval *arr;	//相当于php中function的参数$arr
	if( zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a", &arr) ){
		RETURN_NULL();
	}
	
	zend_hash_apply(Z_ARRVAL_P(arr), php_foreach_body TSRML_CC);	//开始遍历
}

2、有索引遍历

为了能在遍历时同时接收索引的值，可以使用void zend_hash_apply_with_arguments：

typedef int (*apply_func_args_t)(void *pDest,int num_args, va_list args, zend_hash_key *hash_key);
void zend_hash_apply_with_arguments(
	HashTable *ht,
	apply_func_args_t apply_func, 
	int numargs, 	//传递参数的个数，通过指定参数个数，决定va_end()
	...
);//这个函数通过C语言中的可变参数特性来接收参数。

PHP中带索引的遍历

<?php
foreach($arr as $key => $val)
{
	echo "The value of $key is: $val\n";
}
?>

内核中实现：

int php_foreach_body_and_key(zval **val, int num_args, va_list args, zend_hash_key *hash_key){
	zval tmpcopy = **val;	//重新copy一个zval，防止破坏原数据
	
	php_printf("附带参数个数%d<br>", num_args);

	char **a, **b;
	a = va_arg(args, char**);	//args是可变参数的起始地址
	b = va_arg(args, char**);
	php_printf("参数1:%s, 参数2:%s<br>", *a, *b);

	INIT_PZVAL(&tmpcopy);
	zval_copy_ctor(&tmpcopy);
	convert_to_string(&tmpcopy);

	php_printf("The value of ");
	if( hash_key->nKeyLength ){
		PHPWRITE(hash_key->arKey, hash_key->nKeyLength);
	}else{
		php_printf("%ld", hash_key->h);
	}
	php_printf(" is: ");
	PHPWRITE(Z_STRVAL(tmpcopy), Z_STRLEN(tmpcopy));
	php_printf("\n");

	zval_dtor(&tmpcopy);
	
	return ZEND_HASH_APPLY_KEEP;
}

PHP_FUNCTION(foreach_test){
	zval *arr;	//相当于php中function的参数$arr
	if( zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a", &arr) ){
		RETURN_NULL();
	}
	
	char *a="var1", *b="var2"; //可变参数a,b

	zend_hash_apply_with_arguments(arrht, php_foreach_body_and_key, 2, &a, &b);	//开始遍历,并传递2个可参数
}