PHP內核探索：zend_parse_parameters函數

轉載地址：http://www.nowamagic.net/librarys/veda/detail/1467

最簡單的獲取函數調用者傳遞過來的參數便是使用zend_parse_parameters()函數。

zend_parse_parameters()函數的前幾個參數我們直接用內核裏宏來生成便可以了，形式爲：ZEND_NUM_ARGS() TSRMLS_CC，注意兩者之間有個空格，但是沒有逗號。從名字可以看出，ZEND_NUM_ARGS()代表這參數的個數。

緊接着需要傳遞個zend_parse_parameters()函數的參數是一個用於格式化的字符串，就像printf的第一個參數一樣。下面表示了最常用的幾個符號。

參數   代表着的類型
b   Boolean
l   Integer 整型
d   Floating point 浮點型
s   String 字符串
r   Resource 資源
a   Array 數組
o   Object instance 對象
O   Object instance of a specified type 特定類型的對象
z   Non-specific zval 任意類型～
Z   zval**類型
f   表示函數、方法名稱，PHP5.1裏貌似木有... ...

這個函數就像printf()函數一樣，後面的參數是與格式化字符串裏的格式一一對應的。一些基礎類型的數據會直接映射成C語言裏的類型。

ZEND_FUNCTION(sample_getlong)
{
    long foo;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,"l", &foo) == FAILURE)
    {
        RETURN_NULL();
    }
    php_printf("The integer value of the parameter is: %ld\n", foo);
    RETURN_TRUE;
}

一般來說，int和long這兩種數據類型的數據往往是相同的，但也有例外情況。所以我們不應改把long的數組放在一個int裏，尤其是在64位平臺裏，那將引發一些不容易排查的Bug。所以通過zend_parse_parameter()函數接收參數時，我們應該使用內核約定好的那些類型的變量作爲載體。

參數  對應C裏的數據類型
b   zend_bool
l   long
d   double
s   char*, int 前者接收指針，後者接收長度
r   zval*
a   zval*
o   zval*
O   zval*, zend_class_entry*
z   zval*
Z   zval**

注意，所有的PHP語言中的複合類型參數都需要zval*類型來作爲載體，因爲它們都是內核自定義的一些數據結構。我們一定要確認參數和載體的類型一直，如果需要，它可以進行類型轉換，比如把array轉換成stdClass對象。

s和O(字母大寫歐)類型需要單獨說一些，因爲它們都需要兩個載體。我們將在接下來的章節裏瞭解php中對象的具體實現。這樣我們改寫一下我們在第五章定義的一個函數：

<?php
function sample_hello_world($name)
{
    echo "Hello $name!\n";
}
?>

在編寫擴展時，我們需要用zend_parse_parameters()來接收這個字符串:

ZEND_FUNCTION(sample_hello_world)
{
    char *name;
    int name_len;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s",&name, &name_len) == FAILURE)
    {
        RETURN_NULL();
    }
    php_printf("Hello ");
    PHPWRITE(name, name_len);
    php_printf("!\n");
}

如果傳遞給函數的參數數量小於zend_parse_parameters()要接收的參數數量，它便會執行失敗，並返回FAILURE。

如果我們需要接收多個參數，可以直接在zend_parse_paramenters()的參數裏羅列接收載體便可以了，如：

<?php
function sample_hello_world($name, $greeting)
{
    echo "Hello $greeting $name!\n";
}
sample_hello_world('John Smith', 'Mr.');
?>

在PHP擴展裏應該這樣來實現：

ZEND_FUNCTION(sample_hello_world)
{
    char *name;
    int name_len;
    char *greeting;
    int greeting_len;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "ss",&name, &name_len, &greeting, &greeting_len) == FAILURE)
    {
        RETURN_NULL();
    }
    php_printf("Hello ");
    PHPWRITE(greeting, greeting_len);
    php_printf(" ");
    PHPWRITE(name, name_len);
    php_printf("!\n");
}

除了上面定義的參數，還有其它的三個參數來增強我們接受參數的能力，如下：

Type Modifier   Meaning
|               它之前的參數都是必須的，之後的都是非必須的，也就是有默認值的。
!               如果接收了一個PHP語言裏的null變量，則直接把其轉成C語言裏的NULL，而不是封裝成IS_NULL類型的zval。
/               如果傳遞過來的變量與別的變量共用一個zval，而且不是引用，則進行強制分離，新的zval的is_ref__gc==0, and refcount__gc==1.

函數參數的默認值

現在讓我們繼續改寫sample_hello_world(), 接下來我們使用一些參數的默認值，在php語言裏就像下面這樣：

<?php
function sample_hello_world($name, $greeting='Mr./Ms.')
{
    echo "Hello $greeting $name!\n";
}
sample_hello_world('Ginger Rogers','Ms.');
sample_hello_world('Fred Astaire');
?>

此時即可以只向sample_hello_world中傳遞一個參數，也可以傳遞完整的兩個參數。

那同樣的功能我們怎樣在擴展函數裏實現呢？我們需要藉助zend_parse_parameters中的(|)參數，這個參數之前的參數被認爲是必須的，之後的便認爲是非必須的了,如果沒有傳遞，則不會去修改載體。

ZEND_FUNCTION(sample_hello_world)
{
    char *name;
    int name_len;
    char *greeting = "Mr./Mrs.";
    int greeting_len = sizeof("Mr./Mrs.") - 1;
 
 
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s|s",
      &name, &name_len, &greeting, &greeting_len) == FAILURE) {
        RETURN_NULL();
    }
    php_printf("Hello ");
    PHPWRITE(greeting, greeting_len);
    php_printf(" ");
    PHPWRITE(name, name_len);
    php_printf("!\n");
}

如果你不傳遞第二個參數，則擴展函數會被認爲默認而不去修改載體。所以，我們需要自己來預先設置有載體的值，它往往是是NULL，或者一個與函數邏輯有關的值。

每個zval，包括IS_NULL型的zval，都需要佔用一定的內存空間，並且需要cpu的計算資源來爲它申請內存、初始化，並在它們完成工作後釋放掉。但是很多代碼都都沒有意識到這一點。有很多代碼都會把一個null型的值包裹成zval的IS_NULL類型，在擴展開發裏這種操作是可以優化的，我們可以把參數接收城C語言裏的NULL。我們就這一個問題看以下代碼：

ZEND_FUNCTION(sample_arg_fullnull)
{
    zval *val;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z",&val) == FAILURE) {
        RETURN_NULL();
    }
    if (Z_TYPE_P(val) == IS_NULL) {
        val = php_sample_make_defaultval(TSRMLS_C);
    }
    ...
}
ZEND_FUNCTION(sample_arg_nullok)
{
    zval *val;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z!",
                                    &val) == FAILURE) {
        RETURN_NULL();
    }
    if (!val) {
        val = php_sample_make_defaultval(TSRMLS_C);
    }
}

這兩段代碼乍看起來並沒有什麼很大的不同，但是第一段代碼確實需要更多的cpu和內存資源。可能這個技巧在平時並沒多大用，不過技多不壓身，知道總比不知道好。

Forced Separation

當一個變量被傳遞給函數時候，無論它是否被引用，它的refcoung__gc屬性都會加一，至少成爲2。一份是它自己，另一份是傳遞給函數的的copy。在改變這個zval之前，有時會需要提前把它分成實際意義上的兩份copy。這就是"/"格式符的作用。它將把寫時複製的zval提前分成兩個完整獨立的copy，從而使我們可以在下面的代碼中隨意的對其進行操作。否則我們可能需要不停的提醒自己對接收的參數進行分離等操作。Like the NULL flag, this modifier goes after the type it means to impact. Also like the NULL flag, you won't know you need this feature until you actually have a use for it.

zend_get_parameters()

如果你想讓你的擴展能夠兼容老版本的PHP，或者你只想以zval*爲載體來接收參數，便可以考慮使用zend_get_parameters()函數來接收參數。

zend_get_parameters()與zend_parse_parameters()不同，從名字上我們便可以看出，它直接獲取，而不做解析。首先，它不會自動進行類型轉換，所有的參數在擴展實現中的載體都需要是zval*類型的，下面讓我們來看一個最簡單的例子：

ZEND_FUNCTION(sample_onearg)
{
    zval *firstarg;
    if (zend_get_parameters(ZEND_NUM_ARGS(), 1, &firstarg)== FAILURE)
    {
        php_error_docref(NULL TSRMLS_CC, E_WARNING,"Expected at least 1 parameter.");
        RETURN_NULL();
    }
    /* Do something with firstarg... */
}

其次，zend_get_parameters()在接收失敗的時候，並不會自己拋出錯誤，它也不能方便的處理具有默認值的參數。

最後一點與zend_parse_parameters不同的是，它會自動的把所有複合copy-on-write的zval進行強制分離，生成一個嶄新的copy送到函數內部。如果你希望用它其它的特性，而唯獨不需要這個功能，可以去嘗試一下用zend_get_parameters_ex()函數來接收參數。

爲了不對copy-on-write的變量進行分離操作，zend_get_parameters_ex()的參數是zval**類型的，而不是zval*。這個函數不太經常用，可能只會在你碰到一些極端問題時候纔會想到它，而它用起來卻很簡單：

ZEND_FUNCTION(sample_onearg)
{
    zval **firstarg;
    if (zend_get_parameters_ex(1, &firstarg) == FAILURE)
    {
        WRONG_PARAM_COUNT;
    }
    /* Do something with firstarg... */
}

注意zend_get_parameters_ex不需要ZEND_NUM_ARGS()作爲參數，因爲它是在是在後期加入的，那個參數已經不再需要了。

上面例子中還使用了WRONG_PARAM_COUNT宏,它的功能是拋出一個E_WARNING級別的錯誤信息，並自動return。

可變參數

有兩種其它的zend_get_parameter_**函數，專門用來解決參數很多或者無法提前知道參數數目的問題。想一下php語言中var_dump()函數的用法，我們可以向其傳遞任意數量的參數，它在內核中的實現其實是這樣的：

ZEND_FUNCTION(var_dump)
{
    int i, argc = ZEND_NUM_ARGS();
    zval ***args;
 
    args = (zval ***)safe_emalloc(argc, sizeof(zval **), 0);
    if (ZEND_NUM_ARGS() == 0 || zend_get_parameters_array_ex(argc, args) == FAILURE)
    {
        efree(args);
        WRONG_PARAM_COUNT;
    }
    for (i=0; i < argc; i++)
    {
        php_var_dump(args[i], 1 TSRMLS_CC);
    }
    efree(args);
}

程序首先獲取參數數量，然後通過safe_emalloc函數申請了相應大小的內存來存放這些zval**類型的參數。這裏使用了zend_get_parameters_array_ex()函數來把傳遞給函數的參數填充到args中。你可能已經立即想到，還存在一個名爲zend_get_parameters_array()的函數，唯一不同的是它將zval*類型的參數填充到args中，並且需要ZEND_NUM_ARGS()作爲參數。

zhxp_870516

發佈了28 篇原創文章 · 獲贊 9 · 訪問量 25萬+

私信關注

PHP內核探索：zend_parse_parameters函數

函數參數的默認值

Forced Separation

zend_get_parameters()

可變參數

Window 安裝 Python 失敗 0x80070643，發生嚴重錯誤

新浪微博如何實現 SSO 的分析

mmap詳解

NGINX模塊開發入門

eAccelerator安裝與使用

Nginx模塊開發—隊列模型

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結