memprof 技术文档

本文档将详细介绍如何安装、使用 memprof 项目以及如何利用其 API 进行内存分析。

1. 安装指南

依赖关系

memprof 扩展依赖于 libjudy 和 sys/queue.h。

• 在基于 Debian 的发行版上，可以使用以下命令安装依赖：

  apt install libjudy-dev
  

• 在 Alpine 发行版上，可以使用以下命令安装依赖：

  apk add judy-dev bsd-compat-headers
  

• 在 MacOS 上，可以使用以下命令安装依赖：

  brew install traildb/judy/judy
  

使用 PECL 安装

确保安装了上述依赖，然后使用以下命令安装 memprof：

pecl install memprof

在 MacOS 上，可以使用以下命令安装：

JUDY_DIR=$(brew --prefix traildb/judy/judy) pecl install memprof

手动安装

确保安装了上述依赖，然后下载源代码并在源代码目录中运行以下命令：

phpize
./configure
make
make install

如果 libjudy 安装在非标准路径（不是 /usr 或 /usr/local），可以在 configure 命令中指定路径：

./configure --with-judy-dir=/opt/homebrew/Cellar/judy/1.0.5

在 Arch Linux 上安装

Arch Linux 用户可以选择安装非官方的 php-memprof 包，使用 makepkg 或他们的首选 AUR 辅助工具。例如，如果使用 yay：

yay -S php-memprof

2. 项目的使用说明

memprof 扩展可以用于跟踪和分析 PHP 程序中的内存分配和释放，帮助查找内存泄漏的源头。

加载扩展

可以在命令行上为单个脚本加载扩展：

php -dextension=memprof.so script.php

或者永久性地，在 php.ini 文件中加载：

extension=memprof.so

当不进行内存分析时，扩展没有性能开销，因此在开发环境中可以默认加载。

使用示例

最简单的使用 memprof 的方法是让它在程序内存超出限制时自动保存内存分析文件。

步骤 1：在 dump_on_limit 模式下启用内存分析

在请求启动时，如果以下条件之一为真，将启用 dump_on_limit 模式的内存分析：

• 环境变量 MEMPROF_PROFILE 的值为 dump_on_limit
• $_GET["MEMPROF_PROFILE"] 的值为 dump_on_limit
• $_POST["MEMPROF_PROFILE"] 的值为 dump_on_limit

对于命令行脚本，可以设置环境变量：

MEMPROF_PROFILE=dump_on_limit php test.php

对于 Web 脚本，可以设置 $_GET 变量：

curl http://127.0.0.1/test.php?MEMPROF_PROFILE=dump_on_limit

或者 $_POST 变量：

curl -d MEMPROF_PROFILE=dump_on_limit http://127.0.0.1/test.php

步骤 2：转储内存分析文件

在此模式下，如果程序超出内存限制（当 PHP 触发类似 "Fatal error: Allowed memory size of 15728640 bytes exhausted (tried to allocate 1024 bytes)" 的错误时），memprof 会自动保存分析文件。

默认情况下，分析文件保存在 /tmp 或 C:\Windows\Temp 目录下，文件名为 memprof.callgrind.*。

步骤 3：可视化内存分析结果

推荐使用 Kcachegrind（Linux）或 Qcachegrind（MacOS、Windows）来可视化结果。Google Perftools 也是支持的。请参阅 memprof_dump_callgrind() 和相关函数的文档。

3. 项目 API 使用文档

以下是一些常用的 memprof API 函数及其用途：

memprof_enabled()

返回内存分析是否当前启用。

memprof_enabled_flags()

返回内存分析是否启用以及启用了哪些分析特性。

memprof_dump_callgrind(resource $stream)

将当前分析结果以 callgrind 格式转储到指定的文件流。

<?php
memprof_dump_callgrind(fopen("output", "w"));

memprof_dump_pprof(resource $stream)

将当前分析结果以 pprof 格式转储到指定的文件流。

<?php
memprof_dump_pprof(fopen("profile.heap", "w"));

memprof_dump_array()

返回表示当前分析结果的数组。

<?php
$dump = memprof_dump_array();

4. 项目安装方式

memprof 项目可以通过以下方式安装：

1. 使用 PECL 命令行工具安装。
2. 手动下载源代码并进行编译安装。
3. 在 Arch Linux 上使用 AUR 包进行安装。

请按照上述 "安装指南" 部分中的详细步骤进行操作。