萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 內核 HashTable 核心 API 全景解析:zend_hash.h 完整函數列表與架構解讀

前言

HashTable 是 PHP 內核的「瑞士軍刀」:數組、符號表、對象屬性、函數表、類屬性、資源列表……無一不建立在 HashTable 之上。理解其 API 與數據結構,是進階 PHP 內核開發、編寫擴展、優化性能的必修課。本文梳理 zend_hash.h 導出的全部 API,並解析其四大核心組件。

HashTable 四大核心組件

  1. 哈希函數:Time33 (DJBX33A) 算法,zend_hash_func(),將字符串 Key 映射為整數哈希值。
  2. C 數組:Bucket **arBuckets,存儲桶指針,大小為 2 的冪次,動態擴容。
  3. 衝突鏈表:每個 Bucket 通過 pNext/pLast 形成雙向鏈表,解決哈希衝突(Separate Chaining)。
  4. 全局遍歷鏈表:所有 Bucket 通過 pListNext/pListLast 串聯,維護插入順序,支撐 foreach 遍歷。

完整 API 分類速查表

以下為 zend_hash.h 導出的核心 API(PHP 7/8 版本可能增減,以當前版本為準):

初始化/銷毀/複製

_zend_hash_init(ht, nSize, pHashFunction, pDestructor, persistent)
zend_hash_destroy(ht)           // 釋放所有數據與 Bucket
zend_hash_clean(ht)             // 僅清空數據,保留 Bucket 數組
zend_hash_graceful_destroy(ht)  // 安全銷毀(處理遞歸)
zend_hash_copy(target, source, pCopyConstructor, tmp, size)
_zend_hash_merge(target, source, pCopyConstructor, tmp, size, overwrite)
zend_hash_merge_ex(target, source, pCopyConstructor, size, merge_checker_func, pParam)

增/刪/改/查(鍵值操作)

_zend_hash_add_or_update(ht, arKey, nKeyLength, pData, nDataSize, pDest, flag)
_zend_hash_quick_add_or_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest, flag) // 預計算哈希
_zend_hash_index_update_or_next_insert(ht, h, pData, nDataSize, pDest, flag) // 數字索引
zend_hash_del_key_or_index(ht, arKey, nKeyLength, h, flag)
zend_hash_find(ht, arKey, nKeyLength, pData)
zend_hash_quick_find(ht, arKey, nKeyLength, h, pData)
zend_hash_exists(ht, arKey, nKeyLength)
zend_hash_index_find(ht, h, pData)
zend_hash_index_exists(ht, h)

遍歷/指針操作

zend_hash_internal_pointer_reset_ex(ht, pos)
zend_hash_internal_pointer_end_ex(ht, pos)
zend_hash_move_forward_ex(ht, pos)
zend_hash_move_backwards_ex(ht, pos)
zend_hash_get_current_key_ex(ht, str_index, str_length, num_index, duplicate, pos)
zend_hash_get_current_key_type_ex(ht, pos)
zend_hash_get_current_data_ex(ht, pData, pos)
zend_hash_update_current_key_ex(ht, key_type, str_index, str_length, num_index, mode, pos)

應用/遍歷回調

zend_hash_apply(ht, apply_func)
zend_hash_apply_with_argument(ht, apply_func_arg, argument)
zend_hash_apply_with_arguments(ht, apply_func_args, num_args, ...)
zend_hash_reverse_apply(ht, apply_func)

統計/比較/排序

zend_hash_num_elements(ht)
zend_hash_sort(ht, sort_func, compare_func, renumber)
zend_hash_compare(ht1, ht2, compare_func, ordered)
zend_hash_minmax(ht, compare_func, flag, pData)
zend_hash_next_free_element(ht) // 下一個可用數字索引

調試/顯示

zend_hash_display(ht)
zend_hash_display_pListTail(ht)

關鍵數據結構(簡化版)

typedef struct _Bucket {
    ulong h;                // 哈希值(數字索引為索引值)
    uint nKeyLength;        // 鍵長(0 表示數字索引)
    void *pData;            // 數據指針
    void *pDataPtr;         // 指向數據的指針(優化小數據)
    struct _Bucket *pNext;  // 衝突鏈表 next
    struct _Bucket *pLast;  // 衝突鏈表 prev
    struct _Bucket *pListNext; // 全局遍歷 next
    struct _Bucket *pListLast; // 全局遍歷 prev
    char arKey[1];          // 變長鍵名
} Bucket;

typedef struct _hashtable {
    uint nTableSize;        // Bucket 數組大小 (2^n)
    uint nTableMask;        // nTableSize - 1,用於快速取模
    uint nNumOfElements;    // 元素數量
    ulong nNextFreeElement; // 下一個免費數字索引
    Bucket *pInternalPointer; // 遍歷指針
    Bucket *pListHead;      // 全局鏈表頭
    Bucket *pListTail;      // 全局鏈表尾
    Bucket **arBuckets;     // Bucket 指針數組
    dtor_func_t pDestructor; // 數據銷毀回調
    zend_bool persistent;   // 是否持久化分配
    unsigned char nApplyCount; // 遞歸保護計數
    zend_bool bApplyProtection;
} HashTable;

典型應用場景

  • PHP 數組:有序映射,同時支持字符串鍵、數字鍵,迭代順序即插入順序(全局鏈表)。
  • 符號表 (EG(active_symbol_table)):變量名 → zval*,函數/類定義同理。
  • 對象屬性表:obj->properties 為 HashTable,動態屬性存儲。
  • 函數/類/常量表:EG(function_table)、EG(class_table)、EG(zend_constants)。
  • 資源列表:EG(regular_list) 追蹤所有資源(文件句柄、DB 連接等)。

性能優化提示

  • 預分配大小:zend_hash_init(ht, 128, ...) 避免頻繁擴容。
  • 數字索引優先:數字鍵不計算哈希,直接作為索引,插入/查找更快。
  • 避免混合鍵:同一 HashTable 混用字符串/數字鍵會觸發雙重查找邏輯。
  • 引用計數:存儲 zval* 時注意 Z_ADDREF/Z_DELREF,防止內存洩漏或 UAF。

總結

HashTable 以「哈希表 + 雙向鏈表」混合結構,兼顧 O(1) 查找與有序遍歷,支撐了 PHP 靈活的數組語義。熟練掌握 zend_hash_* API,是編寫高性能擴展、理解核心行為、排查疑難雜癥的基石。

copyright © 萬盛學電腦網 all rights reserved