[Übersetzung][PHP-Erweiterungsentwicklung und eingebettet] Kapitel 6 – Rückgabewert

Rückgabewert

Die User-Space-Funktion verwendet das Schlüsselwort return, um Informationen an ihren aufrufenden Space zurückzugeben, was der Syntax der C-Sprache entspricht. Beispiel:

Wenn sample_long() aufgerufen wird, wird 42 zurückgegeben und auf die Variable $bar gesetzt. Der entsprechende Code in der C-Sprache lautet wie folgt:

function sample_long() {  
  return 42;  
}  
$bar = sample_long();

Natürlich in der C-Sprache Sie wissen immer, welche Funktion aufgerufen wird und basierend auf dem Funktionsprototyp zurückgegeben wird. Daher müssen Sie dementsprechend die Variable definieren, in der das Rückgabeergebnis gespeichert wird. Bei der Verarbeitung im PHP-Benutzerbereich ist der Variablentyp dynamisch und hängt davon ab Kapitel 2 „Variableninhalte“ Der in „Outside the World“ eingeführte zval-Typ.

int sample_long(void) {  
  return 42;  
}  
void main(void) {  
  int bar = sample_long();  
}

return_value-Variable

Sie denken vielleicht, dass Ihre interne Funktion direkt einen zval zurückgeben oder einen zval-Speicher zuweisen sollte Leerzeichen eingeben und den zval wie folgt zurückgeben * .

Leider ist dies falsch. Anstatt jede Funktionsimplementierung zu zwingen, einen zval zuzuweisen und ihn zurückzugeben, weist die Zend-Engine diesen Speicherplatz vor dem Funktionsaufruf zu . Der zval-Typ wird dann auf IS_NULL initialisiert und der Wert wird als Parametername return_value übergeben:

PHP_FUNCTION(sample_long_wrong)  
{  
    zval *retval;  
  
    MAKE_STD_ZVAL(retval);  
    ZVAL_LONG(retval, 42);  
  
    return retval;  
}

Es sollte beachtet werden, dass die PHP_FUNCTION()-Implementierung dies tut Es werden keine Werte direkt zurückgegeben, sondern die entsprechenden Daten werden direkt in den Parameter return_value eingefügt, und die Zend-Engine verarbeitet sie, nachdem die interne Funktion ausgeführt wurde.

PHP_FUNCTION(sample_long)  
{  
    ZVAL_LONG(return_value, 42);  
    return;  
}

Freundliche Erinnerung: Das Makro ZVAL_LONG() ist ein Wrapper für mehrere Zuweisungsvorgänge:

Oder direkter:

Z_TYPE_P(return_value) = IS_LONG;  
Z_LVAL_P(return_value) = 42;

Die Attribute is_ref und refcount von return_value sollten nicht direkt durch interne Funktionen geändert werden Wird von der Zend-Engine beim Aufruf Ihrer Funktion initialisiert und verarbeitet.

return_value->type = IS_LONG;  
return_value->value.lval = 42;

Jetzt werfen wir einen Blick auf diese spezielle Funktion und fügen sie der in Kapitel 5 „Ihre erste Erweiterung“ erstellten Beispielerweiterung hinzu Funktion „sample_hello_world()“ und Änderung „sample_long()“ zur Struktur „php_sample_functions“ hinzugefügt:

Jetzt können wir make ausführen, um die Erweiterung neu zu erstellen.

static function_entry php_sample_functions[] = {  
    PHP_FE(sample_hello_world, NULL)  
    PHP_FE(sample_long, NULL)  
    { NULL, NULL, NULL }  
};

Wenn alles in Ordnung ist, können Sie php und ausführen Testen Sie die neue Funktion:

Kompaktere Makros umschließen

$ php -r 'var_dump(sample_long());

Im Hinblick auf die Lesbarkeit und Wartbarkeit des Codes gibt es wiederholte Teile in den ZVAL_*()-Makros: die Variable return_value In diesem Fall ersetzt das Makro ZVAL durch RETVAL, und wir können return_value beim Aufruf weglassen.

Im vorherigen Beispiel kann der Implementierungscode von sample_long() wie folgt reduziert werden:

Die folgende Tabelle listet die RETVAL-Makros in der Zend-Engine auf, die bis auf zwei spezielle Makros mit dem entsprechenden ZVAL-Familienmakro identisch sind, außer dass der return_value-Parameter gelöscht wurde

PHP_FUNCTION(sample_long)  
{  
    RETVAL_LONG(42);  
    return;  
}

Beachten Sie, dass die TRUE- und FALSE-Makros keine Klammern haben. Dies dient dazu, Abweichungen von den Zend/PHP-Codierungsstandards zu berücksichtigen, und die wichtigste wird beibehalten Behalten Sie die Abwärtskompatibilität bei. Wenn Ihre Erweiterung nicht erstellt werden kann, schließen Sie. Wenn Sie die Fehlermeldung „undefiniertes Makro RETVAL_TRUE()“ erhalten, überprüfen Sie bitte, ob Sie beim Schreiben dieser beiden Makros im Code versehentlich die Klammern geschrieben haben.

Normalerweise, wenn Ihre Funktion verarbeitet den Rückgabewert, ist bereit zum Beenden und gibt die Kontrolle an den aufrufenden Bereich zurück. Aus diesem Grund sind einige andere Makros für die Rückgabe interner Funktionen konzipiert: Makros der RETURN_*()-Familie >Obwohl Sie es nicht sehen können, wird diese Funktion tatsächlich zurückgegeben, nachdem das RETURN_LONG()-Makro aufgerufen wurde. Wir können php_printf() am Ende der Funktion zum Testen hinzufügen:

php_printf( ), wie im Inhalt beschrieben, weil RETURN_LONG() implizit aufruft Die Endfunktion.

Wie die RETVAL-Reihe verfügt auch jeder in der vorherigen Tabelle aufgeführte einfache Typ über ein entsprechendes RETURN-Makro RETURN_TRUE- und RETURN_FALSE-Makros verwenden keine Klammern.

PHP_FUNCTION(sample_long)  
{  
    RETURN_LONG(42);  
}

Komplexere Typen wie Objekte und Arrays werden ebenfalls über den Parameter return_value zurückgegeben; sie können jedoch grundsätzlich nicht durch einfache Makros erstellt werden Es verfügt über das RETVAL-Makro und gibt tatsächlich den Ressourcentyp zurück. Es erfordert zusätzliche Arbeit. Wie Sie diese Typen zurückgeben, erfahren Sie in den Kapiteln 8 bis 11.

PHP_FUNCTION(sample_long)  
{  
    RETURN_LONG(42);  
    php_printf("I will never be reached.\n");  
}

Ist es die Mühe wert?

Eins Die intrinsische Zend-Funktionsfunktion, die noch nicht verwendet wird, ist return_value_used Parameters. Betrachten Sie den folgenden User-Space-Code:

Da sample_array_range() das Ergebnis beim Aufruf nicht in einer Variablen speichert, dem 1000-Element Der hier erstellte Array-Speicherplatz wird natürlich völlig verschwendet. Der Aufruf von „sample_array_range()“ auf diese Weise ist dumm, aber was kann man ohne eine gute Möglichkeit tun, die Zukunft vorherzusagen?

Obwohl auf Benutzerbereichsfunktionen nicht zugegriffen werden kann, sind sie intern Funktionen können sich auf den Parameter return_value_used verlassen, der allen internen Funktionen gemeinsam ist.

Um die Funktionsweise dieser Funktion zu sehen, fügen Sie diese Funktion einfach zu Ihrer sample.c-Quelldatei hinzu Setzen Sie es in der Struktur php_sample_functions frei:

function sample_array_range() {  
    $ret = array();  
    for($i = 0; $i < 1000; $i++) {  
        $ret[] = $i;  
    }  
    return $ret;  
}  
sample_array_range();

Übersetzungshinweis: Informationen zum Umgang mit Funktionsrückgabewerten, die nicht im Benutzerbereich verwendet werden, können Sie in der Funktion zend_do_fcall_common_helper_SPEC in Zend/zend_vm_execute.h lesen. Nach der Verarbeitung des internen Funktionsaufrufs wird geprüft, ob der Rückgabewert dieser Funktion verwendet wird. Wenn nicht, wird er entsprechend freigegeben.

Referenzwert zurückgeben

PHP_FUNCTION(sample_array_range)  
{  
    if (return_value_used) {  
        int i;  
        /* 返回从0到999的数组 */  
        array_init(return_value);  
        for(i = 0; i < 1000; i++) {  
            add_next_index_long(return_value, i);  
        }  
        return;  
    } else {  
        /* 提示错误 */  
        php_error_docref(NULL TSRMLS_CC, E_NOTICE,  
               "Static return-only function called without processing output");  
        RETURN_NULL();  
    }  
}

从用户空间的php工作中你可能已经知道了, php函数还可以以引用方式返回值. 由于实现问题, 在php 5.1之前应该避免在内部函数中返回引用, 因为它不能工作. 考虑下面的用户空间代码片段:

function &sample_reference_a() {  
    /* 如果全局空间没有变量$a, 就以初始值NULL创建它 */  
    if (!isset($GLOBALS['a'])) {  
        $GLOBALS['a'] = NULL;  
    }  
    return $GLOBALS['a'];  
}  
$a = 'Foo';  
$b = sample_reference_a();  
$b = 'Bar';

在这个代码片段中, 就像使用$b = &$GLOBALS['a];或者由于在全局空间, 使用$b = &$a; 将$b创建为$a的一个引用.

回顾第3章"内存管理", 在到达最后一行时, $a和$b实际上包含相同的值'Bar'. 现在我们看看内部实现这个函数:

#if (PHP_MAJOR_VERSION > 5) || (PHP_MAJOR_VERSION == 5 && \  
                          PHP_MINOR_VERSION > 0)  
PHP_FUNCTION(sample_reference_a)  
{  
    zval **a_ptr, *a;  
  
  
    /* 从全局符号表查找变量$a */  
    if (zend_hash_find(&EG(symbol_table), "a", sizeof("a"),  
                                          (void**)&a_ptr) == SUCCESS) {  
        a = *a_ptr;  
    } else {  
        /* 如果不存在$GLOBALS['a']则创建它 */  
        ALLOC_INIT_ZVAL(a);  
        zend_hash_add(&EG(symbol_table), "a", sizeof("a"), &a,  
                                              sizeof(zval*), NULL);  
    }  
    /* 废弃旧的返回值 */  
    zval_ptr_dtor(return_value_ptr);  
    if (!a->is_ref && a->refcount > 1) {  
        /* $a需要写时复制, 在使用之前, 必选先隔离 */  
        zval *newa;  
        MAKE_STD_ZVAL(newa);  
        *newa = *a;  
        zval_copy_ctor(newa);  
        newa->is_ref = 0;  
        newa->refcount = 1;  
        zend_hash_update(&EG(symbol_table), "a", sizeof("a"), &newa,  
                                                 sizeof(zval*), NULL);  
        a = newa;  
    }  
    /* 将新的返回值设置为引用方式并增加refcount */  
    a->is_ref = 1;  
    a->refcount++;  
    *return_value_ptr = a;  
}  
#endif /* PHP >= 5.1.0 */

return_value_ptr参数是所有内部函数都会传递的另外一个公共参数, 它是zval **类型, 包含了指向return_value的指针. 通过在它上面调用zval_ptr_dtor(), 默认的return_value的zval *将被释放. 接着可以自由的选择一个新的zval *去替代它, 在这里选择了变量$a, 选择性的进行zval隔离后, 将它的is_ref设置为1, 设置到return_value_ptr中.

如果现在编译运行这段代码, 无论如何你会得到一个段错误. 为了使它可以工作, 你需要在php_sample.h中增加下面的代码:

#if (PHP_MAJOR_VERSION > 5) || (PHP_MAJOR_VERSION == 5 && \  
                          PHP_MINOR_VERSION > 0)  
static  
    ZEND_BEGIN_ARG_INFO_EX(php_sample_retref_arginfo, 0, 1, 0)  
    ZEND_END_ARG_INFO ()  
#endif /* PHP >= 5.1.0 */

译注: 译者使用的php-5.4.9中, ZEND_BEGIN_ARG_INFO_EX的宏定义中已经包含了static修饰符, 因此本书示例中相应的需要进行修改, 请读者在阅读过程中注意这一点.

接着, 在php_sample_functions中声明你的函数时使用这个结构:

#if (PHP_MAJOR_VERSION > 5) || (PHP_MAJOR_VERSION == 5 && \  
                          PHP_MINOR_VERSION > 0)  
    PHP_FE(sample_reference_a, php_sample_retref_arginfo)  
#endif /* PHP >= 5.1.0 */

这个结构你将在本章后面详细学习, 用来向Zend引擎提供函数调用的重要暗示信息. 这里它告诉Zend引擎return_value需要被覆写, 应该从return_value_ptr中得到正确的地址. 如果没有这个暗示, Zend引擎会简单的在return_value_ptr中设置NULL, 这可能使得在执行到zval_ptr_dtor()时程序崩溃.

这段代码每一个片段都包裹在#if块中, 它指示编译器只有在PHP版本大于等于5.1时才启用这个支持. 如果没有这些条件指令, 这个扩展将不能在php4上编译(因为在return_value_ptr中包含的一些元素不存在), 在php5.0中不能提供正确的功能(有一个bug导致返回的引用被以值的方式拷贝)

引用方式返回值

使用return(语法)结构将值和变量回传给调用方是没有问题的, 但是, 有时你需要从一个函数返回多个值. 你可以使用数组(我们将在第8章"使用数组和哈希表工作")达到这个目的, 或者你可以使用参数栈返回值.

调用时引用传值

一种简单的引用传递变量方式是要求调用时在参数变量名前使用取地址符(&), 如下用户空间代码:

function sample_byref_calltime($a) {  
    $a .= ' (modified by ref!)';  
}  
$foo = 'I am a string';  
sample_byref_calltime(&$foo);  
echo $foo;

参数变量名前的取地址符(&)使得发送给函数的是$foo实际的zval, 而不是它的内容拷贝.这就使得函数可以通过传递的这个参数修改这个值来返回信息. 如果调用sample_byref_calltime()时没有在$foo前面使用取地址符(&), 则函数内的修改并不会影响原来的变量.

在C层面重演这个行为并不需要特殊的编码. 在你的sample.c源码文件中sample_long()后面创建下面的函数:

PHP_FUNCTION(sample_byref_calltime)  
{  
    zval *a;  
    int addtl_len = sizeof(" (modified by ref!)") - 1;  
  
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z", &a) == FAILURE) {  
        RETURN_NULL();  
    }  
    if (!a->is_ref) {  
        /* 不是以引用方式传值则不做任何事离开函数 */  
        return;  
    }  
    /* 确保变量是字符串 */  
    convert_to_string(a);  
    /* 扩大a的缓冲区以使可以保存要追加的数据 */  
    Z_STRVAL_P(a) = erealloc(Z_STRVAL_P(a),  
        Z_STRLEN_P(a) + addtl_len + 1);  
    memcpy(Z_STRVAL_P(a) + Z_STRLEN_P(a),  
    " (modified by ref!)", addtl_len + 1);  
    Z_STRLEN_P(a) += addtl_len;  
}

和往常一样, 这个函数需要增加到php_sample_functions结构中.

PHP_FE(sample_byref_calltime,        NULL)

译注: 运行时引用传值在译者使用的版本(php-5.4.9 ZendEngine 2.4.0)中已经被完全废弃. 早前的版本可以在php.ini中使用allow_call_time_pass_reference指令启用. 测试时请注意版本问题.

编译期引用传值

更常用的方式是编译期引用传值. 这里函数的参数定义为只能以引用方式使用, 传递常量或其他中间值(比如函数调用的结果)将导致错误, 因为那样函数就没有地方可以存储结果值去回传了. 用户空间的编译期引用传值代码如下:

function sample_byref_compiletime(&$a) {  
    $a .= ' (modified by ref!)';  
}  
$foo = 'I am a string';  
sample_byref_compiletime($foo);  
echo $foo;

如你所见, 这和调用时引用传值的差别仅在于取地址符的位置不同. 在C的层面上去看这个函数时, 函数代码上是完全相同的. 唯一的区别在于php_sample_functions块中对函数的声明:

PHP_FE(sample_byref_compiletime, php_sample_byref_arginfo)

php_sample_byref_arginfo是一个常量结构, 你需要在使用之前先定义它.

实际上, 编译期引用传值中, 对is_ref检查的代码可以删除, 因为总能保证它是引用方式的. 不过这里留着它也不会有什么危害.

在Zend引擎1(php4)中, 这个结构是一个简单的char *列表, 第一个元素指定了长度, 接下来是描述每个函数参数的标记集合.

static unsigned char php_sample_byref_arginfo[] =  
                                { 1, BYREF_FORCE };

这里, 1表示向量只包含了一个参数的信息. 后面的元素就顺次描述参数特有的标记信息, 第二个元素描述第一个参数. 如果涉及到第二个或第三个参数, 对应的就需要在这个向量中增加第三个和第四个元素. 参数信息的可选值如下表:

在Zend引擎2(php 5+)中, 你将使用一种更加可扩展的结构, 它包含类更多的信息, 比如最小和最大参数要求, 类型暗示, 是否强制引用等.

首先, 参数信息结构使用两个宏中的一个定义. 较简单的一个是ZEND_BEGIN_ARG_INFO(), 它需要两个参数:

ZEND_BEGIN_ARG_INFO(name, pass_rest_by_reference)

name非常简单, 就是扩展中其他地方使用这个结构时的名字, 当前这个例子我们使用的名字是: php_sample_byref_arginfo

pass_rest_by_reference的含义和BYREF_FORCE_REST用在Zend引擎1的参数信息向量最后一个元素时一致. 如果这个参数设置为1, 所有没有在结构中显式描述的参数都被认为是编译期引用传值的参数.

还有一种可选的开始宏, 它引入了两个Zend引擎1没有的新选项, 它是ZEND_BEGIN_ARG_INFO_EX():

ZEND_BEGIN_ARG_INFO_EX(name, pass_rest_by_reference, return_reference,  
                             required_num_args)

当然, name和pass_rest_by_reference和前面所说的是相同的含义. 本章前面也提到了, return_reference是告诉Zend你的函数需要用自己的zval覆写return_value_ptr.

最后一个参数, required_num_args, 它是另外一种类型的暗示, 用来告诉Zend在某种被认为是不完整的调用时完全的跳过函数调用.

在你拥有了一个恰当的开始宏后, 接下来就可以是0个或多个ZEND_ARG_*INFO元素. 这些宏的类型和用法如下表. 

最后, 所有使用Zend引擎2的宏设置的参数信息结构必须使用ZEND_END_ARG_INFO()结束. 对于你的sample函数, 你需要选择一个如下的结构:

ZEND_BEGIN_ARG_INFO(php_sample_byref_arginfo, 0)  
    ZEND_ARG_PASS_INFO(1)  
ZEND_END_ARG_INFO()

为了让扩展兼容Zend引擎1和2, 需要使用#ifdef语句为两者均定义arg_info结构:

#ifdef ZEND_ENGINE_2  
static  
    ZEND_BEGIN_ARG_INFO(php_sample_byref_arginfo, 0)  
        ZEND_ARG_PASS_INFO(1)  
    ZEND_END_ARG_INFO()  
#else /* ZE 1 */  
static unsigned char php_sample_byref_arginfo[] =  
                                { 1, BYREF_FORCE };  
#endif

注意, 这些代码片段是集中在一起的, 现在是时候创建一个真正的编译期引用传值实现了. 首先, 我们将为Zend引擎1和2定义的php_sample_byref_arginfo块放到头文件php_sample.h中.

接下来, 可以有两种选择, 一种是将PHP_FUNCTION(sample_byref_calltime)拷贝一份, 并重命名为PHP_FUNCTION(sample_byref_compiletime), 接着在php_sample_functions中增加一行PHP_FE(sample_byref_compiletime, php_sample_byref_arginfo)

这种方式简单移动, 并且在一段时候后修改时, 更加不容易产生混淆. 因为这里只是示例代码, 因此, 我们可以稍微放松点, 使用你在上一章学的PHP_FALIAS()避免代码重复.

这样, 就不是赋值PHP_FUNCTION(sample_byref_calltime), 而是在php_sample_functions中直接增加一行:

PHP_FALIAS(sample_byref_compiletime, sample_byref_calltime,  
    php_sample_byref_arginfo)

回顾第5章, 这将创建一个名为sample_byref_compiletime()的用户空间函数, 它对应的内部实现是sample_byref_calltime()的代码. php_sample_byref_arginfo是这个版本的特殊之处.

小结

本章你看到了怎样从一个内部函数返回值, 包括直接返回值和引用方式返回, 以及通过参数栈引用返回. 此外还简单了解了Zend引擎2的参数类型暗示结构zend_arg_info.

下一章你将会继续探究接受基本的zval参数以及使用zend_parse_parameters()强大的类型戏法.

以上就是 [翻译][php扩展开发和嵌入式]第6章-返回值的内容，更多相关内容请关注PHP中文网（www.php.cn）！