PHP扩展中使用POSIX pthread库导致执行停滞的问题排查

问题背景 #

正在开发PHP7.4扩展，通过C语言POSIX pthread库创建分离的后台线程（后续用于读取队列消息，当前仅做线程分离返回的验证）。未使用PHP官方pthreads扩展，且环境已验证可编译执行使用pthread库的纯C代码。

创建线程的核心代码：

static int init_thread()
{
    int ret = 0;
    pthread_t thread;
    ret = pthread_create(&thread, NULL, threadFunc, NULL);
    if (ret != 0)
    {
        fprintf(stderr, "pthread_create failed with error code %d\n", ret);
        return -1;
    }
    return 0;
}

调试用线程函数：

static void* threadFunc(void* arg)
{
    pthread_detach(pthread_self());
    return 0;
}

异常现象 #

• init_thread在RINIT阶段调用，仅在PHP-FPM工作进程首次启动时执行（已单独验证RINIT执行时机）。
• 移除pthread_create代码后，扩展的MINIT、GINIT、RINIT阶段的日志打印、文件创建验证均正常；但启用pthread_create后，扩展完全不运行——比如MINIT阶段本该创建的验证文件从未生成（MINIT执行早于RINIT）。
• 尝试将pthread_t改为扩展全局变量，结果一致。
• 已尝试ZTS构建（定义ZTS、COMPILE_DL_EXTNAME并执行ZEND_TSRMLS_CACHE_DEFINE），问题仍存在。
• Nginx和PHP7.4日志无明确错误，网站运行正常但扩展完全失效。

排查思路 #

1. 编译链接阶段验证 #

• 确认扩展config.m4中正确添加pthread库链接参数：在PHP_NEW_EXTENSION前加入PHP_ADD_LIBRARY(pthread, 1, EXTENSION_NAME_SHARED_LIBADD)，确保编译时链接libpthread。
• 用ldd检查生成的.so文件：ldd /path/to/your/extension.so，确认输出包含libpthread.so.0条目。

2. 线程函数合规性检查 #

• 确保threadFunc严格符合POSIX线程函数定义：返回值为void*类型，避免因类型不匹配导致的未定义行为。
• 线程函数中避免直接调用PHP Zend API（当前代码未涉及，但后续开发需注意），同时确认线程创建时的栈大小、调度策略等参数无冲突。

3. 进程启动阶段资源/信号排查 #

• 在pthread_create前重置信号掩码，避免父进程信号限制影响线程启动：

  sigset_t set;
  sigemptyset(&set);
  pthread_sigmask(SIG_SETMASK, &set, NULL);
  

• 增强错误日志输出，用strerror打印具体错误描述（需包含<string.h>）：

  fprintf(stderr, "pthread_create failed: %s (code %d)\n", strerror(ret), ret);
  

• 尝试将线程创建时机从RINIT改为MINIT或GINIT，排查RINIT阶段的特殊限制。

4. PHP-FPM进程管理影响排查 #

• 将PHP-FPM的pm模式设置为static并固定进程数，避免动态进程fork导致线程状态异常。
• 检查PHP-FPM的rlimit_nproc等资源限制配置，确保进程可创建足够线程。

5. 系统级调试 #

• 用strace跟踪PHP-FPM工作进程启动：strace -f -p <php-fpm-worker-pid>，观察pthread_create前后的系统调用是否出现异常（如clone失败、进程意外退出）。
• 用GDB附加到PHP-FPM工作进程，在init_thread和threadFunc设置断点，观察是否能进入断点及线程创建的具体错误。

内容的提问来源于stack exchange，提问作者KeithDeSantis