PHP FFI 调用本地库时如何管理指针生命周期

PHP FFI 管理指针生命周期时，先不要问“什么时候调用 free”，而要先确认“这块内存是谁分配的”。由 FFI::new() 创建且 owned=true 的数据跟随其 FFI\CData 对象；由 FFI::new(..., false) 创建的非托管数据才交给 FFI::free()；本地库返回的句柄必须调用同一库提供的析构函数。FFI::addr() 和 FFI::cast() 只产生非拥有视图，源对象必须活得更久。

PHP FFI 官方手册：https://www.php.net/manual/en/book.ffi.php

一块原生内存只应有一个所有者和一条释放路径。PHP 对象被回收，并不等于任意 C 指针都会被正确释放；保存了一个指针，也不等于它指向的内存仍然有效。

先把三类生命周期分开

排查 FFI 内存问题时，最容易混淆的是 FFI\CData 包装对象、指针视图和底层原生内存。它们可能同时存在，但释放规则不同。

官方手册明确说明，FFI::addr() 创建的是非托管指针，源数据必须比结果指针存活更久；FFI::cast() 也会创建引用同一底层数据的非拥有对象。PHP 8.3 起，静态调用 FFI::new() 和 FFI::cast() 已被标记为弃用，迁移时应优先使用对应 FFI 实例的方法。

旧写法为什么容易留下悬空指针

下面假设本地库提供一个不透明的 buffer_t 句柄。创建和销毁由库负责，写入时会复制传入字节，读取接口返回的地址只在句柄仍有效时可用。

/* buffer.h：所有权规则由本地库公开 */
typedef struct buffer buffer_t;

/* 创建成功后必须与 buffer_destroy 成对 */
buffer_t *buffer_create(size_t capacity);
void buffer_destroy(buffer_t *buf);

/* write 复制数据；data 返回内部只读视图 */
int buffer_write(buffer_t *buf, const char *data, size_t len);
const char *buffer_data(const buffer_t *buf);
size_t buffer_size(const buffer_t *buf);

危险写法通常不是语法错误，而是释放责任隐藏在几个临时变量里：

buffer_create(1024);

// data 只是内部内存视图，handle 销毁后就失效
$view = $ffi->buffer_data($handle);
$ffi->buffer_destroy($handle);

// 错误：此时继续读取 view 可能访问已释放内存
$text = FFI::string($view, 16);

类似问题也会出现在 FFI::addr($temporary) 或 $ffi->cast(..., $temporary) 上。如果最终只把派生指针保存在对象属性中，而源 $temporary 离开作用域，PHP 可以回收真正拥有内存的 CData，派生视图仍有一个看似正常的对象，却已经没有有效底层存储。

本地库句柄要用匹配的析构函数

一个稳妥的迁移原则是：谁分配，谁释放。buffer_create() 的返回值用 buffer_destroy()；另一个库如果提供 widget_alloc()，就应查它对应的 widget_free()。不要因为变量在 PHP 中表现为 FFI\CData，就把所有指针都交给 FFI::free()。

FFI::free() 的用途很窄：手动释放此前由 FFI::new($type, false) 创建的非托管数据。它不是 C 标准库 free() 的通用替身，也不知道第三方库是否使用了自定义分配器、对象池或引用计数。

new('unsigned char[4096]', false);

try {
    // 非托管缓冲区在这里交给同步 C 函数使用
    $ffi->memset($bytes, 0, 4096);
} finally {
    // 仅释放由 FFI::new(..., false) 创建的内存
    FFI::free($bytes);
}

如果 C 函数会在返回后继续保存传入地址，那么即使使用 try/finally 也不能立刻释放。此时要么让 C 端复制数据，要么建立一个跨调用的拥有者对象，把缓冲区和相关指针一起保存到 C 端明确通知完成为止。

把句柄、绑定和关闭状态放进同一个对象

对于稀缺资源，最实用的写法是显式 close() 加析构兜底。业务代码在正常路径调用 close()，析构函数只防止异常分支完全漏掉释放。close() 必须幂等，释放后立即清空句柄，所有公开方法先检查状态。

ffi->buffer_create($capacity);
        if (FFI::isNull($handle)) {
            throw new RuntimeException('buffer_create failed');
        }
        $this->handle = $handle;
    }

    public function write(string $data): void
    {
        $handle = $this->requireOpen();

        // 契约声明 C 端会复制字节，因此调用返回后字符串可释放
        $result = $this->ffi->buffer_write(
            $handle,
            $data,
            strlen($data)
        );
        if ($result !== 0) {
            throw new RuntimeException('buffer_write failed: ' . $result);
        }
    }

    public function read(): string
    {
        $handle = $this->requireOpen();
        $size = $this->ffi->buffer_size($handle);
        $view = $this->ffi->buffer_data($handle);

        // 在 handle 仍存活时立即复制为 PHP 字符串
        return FFI::string($view, $size);
    }

    public function close(): void
    {
        if ($this->handle === null) {
            return; // 幂等：避免重复释放
        }

        $this->ffi->buffer_destroy($this->handle);
        $this->handle = null;
    }

    public function __destruct()
    {
        // 析构只兜底，正常路径仍应显式 close()
        $this->close();
    }

    private function requireOpen(): FFI\CData
    {
        if ($this->handle === null) {
            throw new LogicException('NativeBuffer is closed');
        }
        return $this->handle;
    }
}

这个封装解决了三个问题：业务层拿不到可随意释放的裸句柄；同一个对象同时持有 FFI 绑定与句柄；关闭状态会阻止释放后的再次访问。对于长驻进程，显式关闭尤其重要，因为不能假设请求很快结束或 GC 会在期望时刻运行。

迁移时还要处理 addr 和 cast 的源对象

如果业务确实需要把 FFI::addr() 或 $ffi->cast() 的结果保存到更长生命周期中，必须同时保存源 CData。可以建立一个简单的“租约”对象，让拥有者和视图成为同一个 PHP 对象的属性；只保存视图是不够的。

pointer = $ffi->cast('unsigned char*', $owner);
    }
}

同样的原则适用于回调上下文和异步 C API：只要 C 端可能在当前 PHP 调用返回后继续使用某个地址，就必须把它视为跨调用资源。要为完成通知、取消、关闭和进程退出分别设计释放点，而不是等待一个局部变量自然离开作用域。

回归检查不要只看“没有报错”

指针错误经常不会立即抛出 PHP 异常。迁移后至少覆盖下面这些边界：

• 创建失败：本地库返回空指针时，不进入后续方法，也不调用只接受有效句柄的析构函数。
• 重复关闭：连续两次调用 close() 不会再次触发本地析构。
• 异常路径：写入、解析或业务检查抛异常后，最外层仍会显式关闭包装对象。
• 关闭后访问：所有方法都会抛出清晰异常，不再把空属性传入 C。
• 内部视图：在句柄销毁前将需要的数据复制为 PHP 字符串，不把内部地址返回给业务层长期保存。
• 跨调用指针：源 CData、回调和上下文都由同一租约对象维持到 C 端确认完成。
• 长驻进程：循环创建与关闭后，原生内存不持续上升；测试进程隔离危险用例，避免崩溃影响主测试器。

write('hello ffi');
    $result = $buffer->read();
    assert($result === 'hello ffi');
} finally {
    // 异常路径同样确定释放
    $buffer->close();
}

// 再次关闭应保持安全，不触发第二次 destroy
$buffer->close();

一份可直接使用的迁移清单

1. 为每个 FFI\CData 标注分配者、所有者、借用者和唯一释放函数。
2. 把 PHP 8.3 以后已弃用的静态 FFI::new()、FFI::cast() 调用改为 FFI 实例方法。
3. 只对 FFI::new(..., false) 的结果使用 FFI::free()。
4. 让本地库返回的句柄与该库的 destroy/free 接口严格成对。
5. 保存 addr/cast 视图时，同时保存源 CData 的强引用。
6. 将裸句柄封装进带幂等 close() 的对象，析构函数仅作为兜底。
7. 关闭后把句柄设为 null，所有方法统一检查已关闭状态。
8. 对 C 端会长期保存的字符串、缓冲区和回调建立跨调用租约。

最后可以用一句话判断释放方式：PHP FFI 自己以非托管模式分配的内存，用 FFI::free()；第三方库分配的内存，用第三方库的析构函数；addr 和 cast 得到的指针不拥有内存，因此要延长源对象寿命，而不是为视图再设计一次释放。

相关问题

persistent=true 是否适合普通请求代码

persistent=true 会把结构分配到系统堆，而不是 PHP 请求堆。它并不会自动解决所有权问题，反而会让存活时间跨出普通请求边界。除非预加载或长驻设计明确需要，并且已经安排了进程级释放策略，否则不要把它当成避免 GC 的快捷开关。

析构函数能否替代显式 close

不建议。析构时机可能受引用关系、循环引用和进程终止路径影响。文件句柄、模型上下文、大块原生缓冲区等资源应在业务边界显式关闭，析构仅用于漏网路径。

为什么把 C 指针设为 null 还不够

把 PHP 属性设为 null 只能删除当前包装引用，不能替第三方库调用正确的析构函数。应先执行匹配的 destroy/free，再清空属性，顺序不能颠倒。