PHP扩展的持久化资源（Persistent Resource）：在多请求间共享连接的生命周期管理

好的，下面开始我的讲座：

PHP扩展的持久化资源：在多请求间共享连接的生命周期管理

各位来宾，大家好！今天我们来探讨一个PHP扩展开发中比较高级，但又非常重要的概念：持久化资源。在传统的PHP开发模式中，每个请求都会经历启动、执行、结束的完整生命周期。这意味着，如果在多个请求中都需要连接数据库或进行其他耗时操作，每次请求都会重新建立连接，造成资源浪费和性能损耗。持久化资源的目的，就是为了解决这个问题，实现在多个请求之间共享资源，从而提高性能。

1. 什么是持久化资源？

简单来说，持久化资源就是在PHP请求结束后，仍然保持其状态的资源。这些资源通常是连接到外部服务的句柄，比如数据库连接、网络套接字、消息队列连接等等。通过在多个请求之间复用这些连接，可以避免重复建立连接的开销。

2. 为什么要使用持久化资源？

• 性能提升： 避免了重复建立连接的开销，尤其是在连接建立过程比较耗时的情况下，性能提升非常明显。
• 资源节约： 减少了服务器资源的占用，例如数据库连接数。
• 状态保持： 某些场景下，需要在多个请求之间保持状态，持久化资源可以方便地实现这一点。

3. 如何在PHP扩展中使用持久化资源？

PHP扩展中使用持久化资源的关键在于理解PHP的生命周期以及资源管理机制。我们需要利用zend_resource结构体来封装资源，并使用zend_register_resource和zend_fetch_resource等函数来注册和获取资源。更重要的是，我们需要在扩展的生命周期内正确地管理这些资源，包括创建、销毁和清理。

3.1 定义资源类型

首先，我们需要定义一个资源类型ID。这可以使用zend_register_list_destructors_ex函数来完成：

#include "php.h"

// 定义资源类型 ID
static int le_my_resource;

// 资源析构函数
static void php_my_resource_dtor(zend_resource *rsrc) {
    // 在这里释放资源
    my_resource *resource = (my_resource *)rsrc->ptr;
    if (resource) {
        // 假设 resource 结构体里有一个 connection 指针需要释放
        if (resource->connection) {
            // 关闭连接
            my_close_connection(resource->connection);
        }
        efree(resource); // 释放资源结构体本身
    }
}

// 在 MINIT 函数中注册资源类型
PHP_MINIT_FUNCTION(my_extension) {
    le_my_resource = zend_register_list_destructors_ex(php_my_resource_dtor, NULL, "My Resource", module_number);
    return SUCCESS;
}

这里，zend_register_list_destructors_ex函数注册了一个资源类型，并指定了析构函数php_my_resource_dtor。当资源不再使用时，PHP会自动调用这个析构函数来释放资源。php_my_resource_dtor函数是资源销毁的核心，它负责释放所有与资源相关的内存和连接。

3.2 创建和注册资源

接下来，我们需要编写代码来创建资源，并将其注册到PHP的资源管理器中：

// 定义资源结构体
typedef struct _my_resource {
    // 资源数据
    void *connection; // 例如，数据库连接句柄
    // 其他资源相关的数据
} my_resource;

PHP_FUNCTION(my_create_resource) {
    my_resource *resource;

    // 创建资源结构体
    resource = (my_resource *)emalloc(sizeof(my_resource));
    if (!resource) {
        RETURN_FALSE; // 内存分配失败
    }

    // 初始化资源 (连接数据库或其他操作)
    resource->connection = my_open_connection(); // 假设有这么一个函数
    if (!resource->connection) {
        efree(resource);
        RETURN_FALSE; // 连接失败
    }

    // 将资源注册到 PHP
    zend_resource *zr = zend_register_resource(resource, le_my_resource);

    // 返回资源 ID
    RETURN_RES(zr);
}

在这个例子中，my_create_resource函数首先分配了一个my_resource结构体的内存，然后调用my_open_connection函数来建立连接。最后，使用zend_register_resource函数将资源注册到PHP的资源管理器中，并返回资源ID。RETURN_RES宏将资源ID返回给PHP脚本。

3.3 获取和使用资源

在PHP脚本中创建资源后，我们需要在其他函数中获取和使用它。这可以使用zend_fetch_resource函数来完成：

PHP_FUNCTION(my_use_resource) {
    zend_resource *res;
    zval *resource_id;
    my_resource *resource;

    // 获取资源 ID
    ZEND_PARSE_PARAMETERS_START(1, 1)
        Z_PARAM_ZVAL(resource_id) // 接收 zval 类型的参数，通常是资源ID
    ZEND_PARSE_PARAMETERS_END();

    // 从资源管理器中获取资源
    resource = (my_resource *)zend_fetch_resource(Z_RES_P(resource_id), "My Resource", le_my_resource);

    if (!resource) {
        RETURN_FALSE; // 资源不存在或类型不匹配
    }

    // 使用资源
    my_query(resource->connection, "SELECT * FROM my_table"); // 假设有这么一个函数
    RETURN_TRUE;
}

my_use_resource函数首先使用ZEND_PARSE_PARAMETERS宏来解析PHP脚本传递的参数，获取资源ID。然后，使用zend_fetch_resource函数从资源管理器中获取资源。如果资源存在且类型匹配，就可以使用它了。

3.4 持久化资源的关键：PHP_RSHUTDOWN_FUNCTION

以上只是创建，注册，和使用资源，并没有涉及到持久化。真正的持久化发生在请求结束时。PHP提供了一个PHP_RSHUTDOWN_FUNCTION，它会在每个请求结束时被调用。我们可以在这个函数中判断资源是否需要被持久化，如果需要，就阻止资源的析构。

static HashTable my_persistent_resources; // 用于存储持久化资源的哈希表

PHP_RINIT_FUNCTION(my_extension) {
    // RINIT 每次请求开始时被调用
    return SUCCESS;
}

PHP_RSHUTDOWN_FUNCTION(my_extension) {
    // RSHUTDOWN 每次请求结束时被调用

    zend_resource *res;
    zend_string *key;
    zend_ulong num_key;

    // 遍历所有资源，检查是否需要持久化
    ZEND_HASH_FOREACH_STR_KEY_VAL(&EG(regular_list), key, num_key, res) {
        if (res->type == le_my_resource) { // 检查是否为我们的资源类型
            my_resource *resource = (my_resource *)res->ptr;

            // 在这里添加逻辑来判断是否需要持久化该资源
            // 例如，可以根据配置选项或资源的状态来决定

            if (should_persist_resource(resource)) { // 假设有这么一个函数来判断
                // 将资源从 EG(regular_list) 移动到 my_persistent_resources
                zend_resource *new_res = zend_register_resource(resource, le_my_resource);
                zend_hash_update(&my_persistent_resources, key, new_res);
                zend_hash_del(&EG(regular_list), key);
                zend_string_release(key);
            }
        }
    } ZEND_HASH_FOREACH_END();

    return SUCCESS;
}

PHP_MSHUTDOWN_FUNCTION(my_extension) {
    // MSHUTDOWN 模块卸载时被调用，需要释放所有持久化资源
    zend_resource *res;
    zend_string *key;

    ZEND_HASH_FOREACH_STR_KEY_VAL(&my_persistent_resources, key, res) {
        php_my_resource_dtor(res); // 调用析构函数释放资源
        zend_string_release(key);
    } ZEND_HASH_FOREACH_END();
    zend_hash_destroy(&my_persistent_resources);

    return SUCCESS;
}

PHP_MINIT_FUNCTION(my_extension) {
    le_my_resource = zend_register_list_destructors_ex(php_my_resource_dtor, NULL, "My Resource", module_number);
    zend_hash_init(&my_persistent_resources, 0, NULL, ZVAL_PTR_DTOR, 1); // 初始化哈希表
    return SUCCESS;
}

在这个例子中：

• 我们定义了一个哈希表my_persistent_resources来存储持久化资源。
• 在PHP_RSHUTDOWN_FUNCTION中，我们遍历所有资源，检查它们的类型是否为le_my_resource。
• 如果资源需要被持久化（通过should_persist_resource函数判断），我们将它从EG(regular_list)（EG代表 Engine Globals, EG(regular_list) 存储着请求级的资源）移动到my_persistent_resources。关键步骤是先重新注册一个资源并添加到my_persistent_resources，然后从EG(regular_list)中删除旧的资源。
• 在PHP_MSHUTDOWN_FUNCTION中，我们遍历my_persistent_resources，并调用析构函数php_my_resource_dtor来释放所有持久化资源。这是非常重要的，否则会导致内存泄漏。
• 在PHP_MINIT_FUNCTION中，我们初始化了哈希表my_persistent_resources。

3.5 资源持久化的实现细节

• 资源标识： 为了在多个请求之间识别和复用资源，需要为每个资源分配一个唯一的标识符。这个标识符可以是数据库连接字符串、套接字地址等等。可以使用哈希算法将这些信息转换为一个唯一的字符串。
• 资源查找： 在PHP_RINIT_FUNCTION中，我们需要检查是否存在与当前请求相关的持久化资源。如果存在，就将其从my_persistent_resources移动到EG(regular_list)，以便在当前请求中使用。
• 资源清理： 如果某个资源在一段时间内没有被使用，或者达到了最大连接数限制，就应该将其释放，以避免资源浪费。可以在PHP_RSHUTDOWN_FUNCTION中添加相应的逻辑。
• 线程安全： 如果PHP运行在多线程模式下，需要确保资源管理的代码是线程安全的。可以使用锁或其他同步机制来保护共享资源。

4. 代码示例：数据库连接池

下面是一个简单的数据库连接池的示例。它演示了如何使用持久化资源来实现数据库连接的复用。

// 数据库连接池结构体
typedef struct _db_connection_pool {
    MYSQL *connection;
    char *host;
    char *user;
    char *password;
    char *database;
    int port;
    zend_long flags;
} db_connection_pool;

static int le_db_connection_pool;
static HashTable persistent_db_connections;

static void php_db_connection_pool_dtor(zend_resource *rsrc) {
    db_connection_pool *pool = (db_connection_pool *)rsrc->ptr;

    if (pool) {
        if (pool->connection) {
            mysql_close(pool->connection);
        }
        efree(pool->host);
        efree(pool->user);
        efree(pool->password);
        efree(pool->database);
        efree(pool);
    }
}

PHP_MINIT_FUNCTION(my_extension) {
    le_db_connection_pool = zend_register_list_destructors_ex(php_db_connection_pool_dtor, NULL, "MySQL Connection Pool", module_number);
    zend_hash_init(&persistent_db_connections, 0, NULL, ZVAL_PTR_DTOR, 1);
    return SUCCESS;
}

PHP_MSHUTDOWN_FUNCTION(my_extension) {
    zend_resource *res;
    zend_string *key;

    ZEND_HASH_FOREACH_STR_KEY_VAL(&persistent_db_connections, key, res) {
        php_db_connection_pool_dtor(res);
        zend_string_release(key);
    } ZEND_HASH_FOREACH_END();
    zend_hash_destroy(&persistent_db_connections);

    return SUCCESS;
}

PHP_RSHUTDOWN_FUNCTION(my_extension) {
    zend_resource *res;
    zend_string *key;
    zend_ulong num_key;

    ZEND_HASH_FOREACH_STR_KEY_VAL(&EG(regular_list), key, num_key, res) {
        if (res->type == le_db_connection_pool) {
            db_connection_pool *pool = (db_connection_pool *)res->ptr;

            // 这里总是持久化连接池，可以添加更复杂的逻辑
            zend_resource *new_res = zend_register_resource(pool, le_db_connection_pool);
            zend_hash_update(&persistent_db_connections, key, new_res);
            zend_hash_del(&EG(regular_list), key);
            zend_string_release(key);
        }
    } ZEND_HASH_FOREACH_END();

    return SUCCESS;
}

PHP_FUNCTION(db_connect_persistent) {
    char *host = "localhost";
    size_t host_len = strlen(host);
    char *user = "root";
    size_t user_len = strlen(user);
    char *password = "";
    size_t password_len = strlen(password);
    char *database = "";
    size_t database_len = strlen(database);
    zend_long port = 3306;
    zend_long flags = 0;

    ZEND_PARSE_PARAMETERS_START(0, 6)
        Z_PARAM_OPT_STRING(host, host_len)
        Z_PARAM_OPT_STRING(user, user_len)
        Z_PARAM_OPT_STRING(password, password_len)
        Z_PARAM_OPT_STRING(database, database_len)
        Z_PARAM_OPT_LONG(port)
        Z_PARAM_OPT_LONG(flags)
    ZEND_PARSE_PARAMETERS_END();

    // 创建连接池标识符
    char identifier[256];
    snprintf(identifier, sizeof(identifier), "%s:%ld@%s/%s", host, port, user, database);
    zend_string *key = zend_string_init(identifier, strlen(identifier), 0);

    // 尝试从持久化连接中获取
    zend_resource *found_res = zend_hash_find_ptr(&persistent_db_connections, key);
    if (found_res && found_res->type == le_db_connection_pool) {
        // 找到持久化连接，将其重新注册到EG(regular_list)
        db_connection_pool *pool = (db_connection_pool*)found_res->ptr;
        zend_resource *new_res = zend_register_resource(pool, le_db_connection_pool);

        // 从持久化连接移除
        zend_hash_del(&persistent_db_connections, key);

        zend_string_release(key);
        RETURN_RES(new_res); // 返回资源ID
    }

    zend_string_release(key);

    // 创建新的连接池
    db_connection_pool *pool = emalloc(sizeof(db_connection_pool));
    pool->host = estrdup(host);
    pool->user = estrdup(user);
    pool->password = estrdup(password);
    pool->database = estrdup(database);
    pool->port = port;
    pool->flags = flags;

    MYSQL *connection = mysql_init(NULL);
    if (!connection) {
        efree(pool->host);
        efree(pool->user);
        efree(pool->password);
        efree(pool->database);
        efree(pool);
        RETURN_FALSE;
    }

    if (!mysql_real_connect(connection, host, user, password, database, port, NULL, flags)) {
        mysql_close(connection);
        efree(pool->host);
        efree(pool->user);
        efree(pool->password);
        efree(pool->database);
        efree(pool);
        RETURN_FALSE;
    }

    pool->connection = connection;

    // 注册资源并返回资源ID
    zend_resource *res = zend_register_resource(pool, le_db_connection_pool);
    RETURN_RES(res);
}

PHP_FUNCTION(db_query) {
    zend_resource *res;
    zval *resource_id;
    char *query;
    size_t query_len;

    ZEND_PARSE_PARAMETERS_START(2, 2)
        Z_PARAM_ZVAL(resource_id)
        Z_PARAM_STRING(query, query_len)
    ZEND_PARSE_PARAMETERS_END();

    db_connection_pool *pool = (db_connection_pool *)zend_fetch_resource(Z_RES_P(resource_id), "MySQL Connection Pool", le_db_connection_pool);

    if (!pool || !pool->connection) {
        RETURN_FALSE;
    }

    if (mysql_query(pool->connection, query)) {
        php_error_docref(NULL, E_WARNING, "MySQL query failed: %s", mysql_error(pool->connection));
        RETURN_FALSE;
    }

    RETURN_TRUE;
}

在这个示例中：

• db_connect_persistent函数用于建立持久化的数据库连接。它首先尝试从persistent_db_connections哈希表中查找现有的连接。如果找到，就直接返回该连接。如果没有找到，就创建一个新的连接，并将其注册到资源管理器中。
• db_query函数用于执行SQL查询。它首先从资源管理器中获取数据库连接，然后执行查询。
• PHP_RSHUTDOWN_FUNCTION函数用于将数据库连接从EG(regular_list)移动到persistent_db_connections，从而实现持久化。
• PHP_MSHUTDOWN_FUNCTION函数用于释放所有持久化的数据库连接。

5. 注意事项

• 内存泄漏： 如果资源没有被正确释放，会导致内存泄漏。务必在PHP_MSHUTDOWN_FUNCTION中释放所有持久化资源。
• 资源冲突： 如果多个请求同时访问同一个资源，可能会导致资源冲突。可以使用锁或其他同步机制来解决这个问题。
• 资源过期： 如果资源长时间没有被使用，可能会过期失效。需要在代码中处理资源过期的情况。
• 错误处理： 在资源创建、获取和使用过程中，可能会发生错误。需要在代码中进行适当的错误处理。
• 配置管理： 持久化资源的行为通常需要通过配置选项来控制。例如，可以设置最大连接数、连接超时时间等等。

6. 总结：理解资源生命周期，妥善管理持久化连接

持久化资源是PHP扩展开发中一个重要的概念，它可以显著提高性能和资源利用率。通过理解PHP的生命周期以及资源管理机制，可以有效地使用持久化资源来优化应用程序。关键在于在请求结束时将资源保存，并在新的请求开始时重新启用，确保及时释放不再需要的资源。记住，管理持久化资源需要特别注意内存泄漏、资源冲突和错误处理。