源码分析 - 她和她的猫 https://her-cat.com/categories/%E6%BA%90%E7%A0%81%E5%88%86%E6%9E%90/ 源码分析的文章列表 - 她和她的猫 她和她的猫 https://her-cat.com/assets/favorite.jpeg https://her-cat.com/assets/favorite.jpeg Hugo -- 0.148.1 zh Wed, 15 Oct 2025 23:26:52 +0800 深入 Hyperf：Inject 注解是如何工作的？ https://her-cat.com/posts/2024/08/25/how-does-hyperf-inject-annotation-work/ Sun, 25 Aug 2024 19:17:00 +0800 https://her-cat.com/posts/2024/08/25/how-does-hyperf-inject-annotation-work/ 本文详细介绍了 Hyperf 框架中 Inject 注解的工作原理，并深入剖析了代理类生成、类实例化过程的拦截机制以及属性值的自动注入操作。 周五的时候，我在 Hyperf 群里看到有群友提出了一个问题：为什么 Inject 注解在使用 new 关键字实例化类时依然能够生效？按理说，Inject 注解不是应该只在通过容器实例化类时才会起作用吗？这个问题引发了群友们的讨论和猜测，甚至有人感叹，Inject 注解的实现简直就是魔法！

对于这个问题，Hyperf 的作者作出了解答：新版本的注入机制通过代理类来实现，注解之所以在 new 关键字下依然有效，是因为实例化的实际上是代理类，而代理类的构造函数中包含了注入操作。

然而，如果我们继续深究，还会发现一些问题：Hyperf 是否为所有类都生成了代理类？又是如何在类实例化时拦截 new 关键字的行为，从而实现实例化的是代理类而非原始类？在属性值注入过程中，具体都执行了哪些操作？

由于微信群本身不太适合深入讨论这些复杂的问题，而且考虑到「深入 Hyperf」系列已经有半年多没更新了，所以我决定撰写这篇文章，逐一解答这些问题，带大家深入探索 Inject 注解的工作原理。

是否为所有类生成了代理类？

Hyperf 生成的所有代理类都保存在 runtime/container/proxy 目录中，仔细观察一下就会发现，这个目录只包含了部分原始类的代理类。

由此可知，Hyperf 不会为所有类生成代理类。

那么，Hyperf 会为哪些类生成代理类呢？答案是，所有需要被切面（Aspect）介入的类。

在 Hyperf 中，可以通过切面介入到任意类的任意方法的执行流程中，从而改变或加强原方法的功能，这就是 AOP（Aspect Oriented Programming）面向切面编程。切面包含了要介入的目标，以及实现对原方法的修改加强处理。这里的介入目标包含了类/方法或者注解，意味着你可以通过类名/方法名称直接指定要介入的类/方法，或者通过注解间接地指定要介入的类/方法。

为了实现 Inject 自动注入的功能，Hyperf 添加了一个 Inject 切面，其介入的目标是使用了 Inject 注解的类。

class InjectAspect extends AbstractAspect
{
    public array $annotations = [
        Inject::class,
    ];

    public function process(ProceedingJoinPoint $proceedingJoinPoint)
    {
        // Do nothing, just to mark the class should be generated to the proxy classes.
        return $proceedingJoinPoint->process();
    }
}

一旦我们在某个类中使用了 Inject 注解，Hyperf 就会为这个类生成代理类。并且从注释中可以看到，Inject 切面不会修改原始方法的任何行为，只是用来标记需要为其生成代理类。

除了 Inject 切面以外，Hyperf 中还包含了很多其它的切面，你可以使用 AspectCollector::list() 获取这些切面。你也可以查看 Hyperf 文档 学习如何自定义切面，提高程序的可重用性以及开发效率。

为什么被实例化的是代理类？

这一切的关键在于 Hyperf 巧妙地利用了 Composer 类自动加载机制，让我们来了解一下其中的细节。

通常情况下，使用了 Composer 的框架都会在入口文件引入一个 /vendor/autoload.php 文件，以启用自动加载功能。在这个文件中，Composer 会通过 spl_autoload_register 函数向 PHP 注册自己的类加载器（ClassLoader）。当我们在 PHP 中使用了当前内存中尚未定义的类的时候（例如使用 new 关键字实例化某个类），PHP 会调用已注册的类加载器，将这个类文件加载到内存中，也就实现了我们常说的自动加载。

在 Composer 的类加载器中，有一个 classMap 数组属性，其键是包含命名空间的类名，值是类的文件路径。示例如下：

array:5 [  
  "Hyperf\Cache\AnnotationManager" => "/code/project/vendor/composer/../hyperf/cache/src/AnnotationManager.php"  
  "Hyperf\Cache\Annotation\CacheAhead" => "/code/project/vendor/composer/../hyperf/cache/src/Annotation/CacheAhead.php"  
  "Hyperf\Cache\Annotation\CacheEvict" => "/code/project/vendor/composer/../hyperf/cache/src/Annotation/CacheEvict.php"  
  "Hyperf\Cache\Annotation\CachePut" => "/code/project/vendor/composer/../hyperf/cache/src/Annotation/CachePut.php"  
  "Hyperf\Cache\Annotation\Cacheable" => "/code/project/vendor/composer/../hyperf/cache/src/Annotation/Cacheable.php"  
]

当 Composer 的类加载器运行时，它会先检查 classMap 数组中是否已经存在这个类。如果类不存在，加载器将按照 PSR-4 或 PSR-0 的规范依次查找类文件；如果存在或找到了类文件，就会使用 include 加载这个类文件。

从整个自动加载过程可以看出，只要在使用某个类之前，将其代理类的路径添加到 classMap 数组中，那么当我们在 PHP 中实例化这个类时，Composer 就会直接加载代理类，而不是原始类。

实际上，Hyperf 确实是这样实现的。在生成所有代理类后，Hyperf 会将原始类与代理类的映射关系添加到 Composer 的 classMap 数组中：

$proxyFileDirPath = BASE_PATH . '/runtime/container/proxy/';
$composerLoader = Composer::getLoader();    
  
$scanner = new Scanner($config, $handler);  
$composerLoader->addClassMap( 
	// 在 scan 方法中完成了扫描与生成代理类
    $scanner->scan($composerLoader->getClassMap(), $proxyFileDirPath)  
);

因此，当你在 Hyperf 中使用那些已经生成了代理类的类时，加载的就是 /runtime/container/proxy 目录下的代理类，而非原始类。

Inject 自动注入的过程

属性值的注入操作是在代理类的构造函数中完成的，因此我们需要通过对比原始类与代理类的内容来进一步分析。

从图片中可以看出，代理类相较于原始类增加了以下内容：

  • 引入了 ProxyTrait 和 PropertyHandlerTrait
  • 在构造函数中调用了 Trait 中的 __handlePropertyHandler 方法
  • 将原始类 user 方法的内容封装为匿名函数，并作为 self::__proxyCall 方法的参数

其中，ProxyTrait 和 self::__proxyCall 是 AOP 功能的核心部分。由于 Inject 切面并不会修改原始方法的行为，我们可以暂时忽略这部分内容，专注于属性值注入的过程。

当我们实例化某个类时，PHP 会自动调用这个类的构造函数。而构造函数中的 __handlePropertyHandler 方法也会随之被调用。由于类里面不仅仅包含当前类的属性，还可能包含 Trait 和继承自父类的属性，因此 __handlePropertyHandler 方法会通过 PropertyHandlerTrait 中的 __handle 方法，依次为当前类、Trait 以及父类的属性完成注入操作。

在 __handle 方法中，Hyperf 会遍历提供的属性列表，并根据属性上的 Inject 注解，从 PropertyHandlerManager 中找到相应的回调函数并调用。

Inject 注解的回调函数是在 Hyperf 启动时注册的，该函数会通过属性的类型名称（即类名）从容器中获取到相应的实例，然后通过反射将实例设置为该属性的值，从而完成注入。

$reflectionProperty = ReflectionManager::reflectProperty($currentClassName, $property);  
$reflectionProperty->setAccessible(true);  
$container = ApplicationContext::getContainer();  
if ($container->has($annotation->value)) {  
    $reflectionProperty->setValue($object, $container->get($annotation->value));  
} elseif ($annotation->required) {  
    throw new NotFoundException("No entry or class found for '{$annotation->value}'");  
}

当类实例化完成后，类里面所有使用了 Inject 注解的属性，也就完成了属性值的自动注入。

总结

以上就是关于 Inject 的全部内容了，希望这篇文章能够帮助你更好地理解和使用这些组件。

]]> 深入 Hyperf：HTTP 服务是如何处理请求的？ https://her-cat.com/posts/2023/12/30/how-does-hyperf-http-server-handle-requests/ Sat, 30 Dec 2023 22:06:00 +0800 https://her-cat.com/posts/2023/12/30/how-does-hyperf-http-server-handle-requests/ 本文详细介绍了 Hyperf 框架中 HTTP 服务处理请求的整个过程。 上一篇文章介绍了 HTTP 服务启动时发生了什么，让我们对于 Hyperf 框架以及 HTTP 服务的启动过程有了更进一步的理解。今天我们继续来了解一下，当我们访问 HTTP 服务时，它是如何处理请求并返回响应内容的。

在 HTTP 服务启动时，Hyperf 会向 Swoole 注册请求事件处理函数。当收到 HTTP 请求时，Swoole 会调用该函数。

在 HTTP 服务启动后，当我们向 HTTP 服务发送请求时，HTTP 请求会被发送到 Swoole 中。Swoole 会将 HTTP 报文解析成 HTTP 请求对象，并构造出一个 HTTP 响应对象。

接着，Swoole 会调用请求事件处理函数，将请求和响应对象作为参数传递给该函数。在该函数中完成对请求的处理，并调用响应对象发送响应内容。

在这篇文章中，我们将分三个部分介绍 Hyperf 中 HTTP 服务处理请求的过程，在第一部分将会介绍如何注册 HTTP 服务的请求事件处理函数，第二部分会介绍如何处理 HTTP 请求并发送响应内容。

注册请求事件处理函数

在 HTTP 服务启动时，Hyperf 需要向 Swoole 注册请求事件处理函数，那么在 Hyperf 中这个处理函数是什么呢？

在 HTTP 服务「读取服务配置」阶段，会从 config/autoload/server.php 配置文件中获取配置信息，其中 Event::ON_REQUEST 是请求事件的枚举值，Hyperf\HttpServer\Server::onRequest() 就是请求事件的处理函数。

return [
    ...
    'servers' => [
        [
            ...
            'callbacks' => [
                Event::ON_REQUEST => [Hyperf\HttpServer\Server::class, 'onRequest'],
            ],
        ],
    ],
    ...
]

在「初始化 HTTP 服务」阶段，将请求事件处理函数注册到 Swoole 中，这部分工作的主要内容如下所示：

foreach ($events as $event => $callback) {
    ...
    [$className, $method] = $callback;    
    $class = $this->container->get($className);
    if (method_exists($class, 'setServerName')) {
        // 设置服务名称
        $class->setServerName($serverName);
    }    // 初始化核心中间件
    if ($class instanceof MiddlewareInitializerInterface) {
        $class->initCoreMiddleware($serverName);
    }
    ...
    // 注册事件处理函数
    $server->on($event, $callback);
}

在 initCoreMiddleware() 方法中，初始化了 HTTP 服务的路由信息，并且通过服务名称获取该 HTTP 服务的中间件以及异常处理器。

public function initCoreMiddleware(string $serverName): void  {    
    $this->serverName = $serverName;  
    $this->coreMiddleware = $this->createCoreMiddleware();    
    $config = $this->container->get(ConfigInterface::class);    
    $this->middlewares = $config->get('middlewares.' . $serverName, []);    
    $this->exceptionHandlers = $config->get('exceptions.handler.' . $serverName, $this->getDefaultExceptionHandler());  
}

处理 HTTP 请求

通过上面的内容我们可以知道，处理 HTTP 请求的逻辑是在 Hyperf\HttpServer\Server::onRequest() 方法中完成的，该方法的原型如下：

public function onRequest($request, $response): void

对于 Hyperf\HttpServer\Server::onRequest() 方法来说，我把它执行的工作分成了以下几个阶段。

初始化请求和响应对象

在这一阶段中，需要初始化 PSR-7 请求和响应对象。这是因为，Hyperf 的标准组件都是基于 PSR 标准实现的，而底层框架可能并没有基于 PSR 标准实现，因此需要先进行兼容性适配。

[$psr7Request, $psr7Response] = $this->initRequestAndResponse($request, $response);

在 initRequestAndResponse() 方法中，先判断对象是否基于 PSR 标准，如果不是，则将其转换成 PSR-7 请求和响应对象。

匹配请求的路由信息

在这一阶段中，调用 Hyperf\HttpServer\CoreMiddleware::dispatch() 方法，使用上面初始化好的 PSR-7 请求对象匹配路由信息。

$psr7Request = $this->coreMiddleware->dispatch($psr7Request);

在 dispatch() 方法中，使用请求对象的请求方式、请求地址匹配 HTTP 服务中的路由信息，将匹配结果转换成 Hyperf\HttpServer\Router\Dispatched 对象，并保存到新的请求对象的属性中并返回。

public function dispatch(ServerRequestInterface $request): ServerRequestInterface  
{  
    $routes = $this->dispatcher->dispatch($request->getMethod(), $request->getUri()->getPath());  
  
    $dispatched = new Dispatched($routes);  
    return Context::set(ServerRequestInterface::class, $request->withAttribute(Dispatched::class, $dispatched));  
}

看到这里，你可能会有疑问，为什么不将 Dispatched 直接保存到原来的请求对象的属性中？

因为这是 PSR-7 标准规定的。在 PSR-7 标准中，请求被认为是不可变的；必须实现所有可能更改状态的方法，以便它们保留当前请求的内部状态，并返回包含更改状态的实例。

也就是说，如果你想修改请求对象中的信息，那么你必须从当前对象中克隆一个新的对象，然后在新的对象中进行修改并返回新的对象。下面是 withAttribute 方法的实现：

public function withAttribute($name, $value)  
{  
    $clone = clone $this;  
    $clone->attributes[$name] = $value;  
    return $clone;
}

知道了这一点之后，相信你以后再也不会有「为什么我设置了属性但是却拿不到值」这种疑惑了。

准备全局和路由中间件

在 HTTP 服务中，中间件根据作用范围分为两种：全局中间件和路由中间件。

全局中间件会被应用到所有路由上，而路由中间件仅应用到部分路由上，是否应用需要根据路由匹配结果来决定。如果匹配到了路由，则从中间件管理器中获取该路由的中间件。否则，仅使用全局中间件。

$dispatched = $psr7Request->getAttribute(Dispatched::class);  
// 获取全局中间件  
$middlewares = $this->middlewares;  
// 判断是否匹配到了路由  
if ($dispatched->isFound()) {  
    // 通过服务名称、请求地址、请求方式获取路由中间件  
    $registeredMiddlewares = MiddlewareManager::get($this->serverName, $dispatched->handler->route, $psr7Request->getMethod());  
    $middlewares = array_merge($middlewares, $registeredMiddlewares);  
}

在一切准备就绪后，Hyperf 会调用 Hyperf\Dispatcher\HttpDispatcher::dispatch() 方法，将请求对象依次交给每个中间件进行处理，然后调用核心中间件的 Hyperf\HttpServer\CoreMiddleware::process() 方法进行最终处理。

$psr7Response = $this->dispatcher->dispatch($psr7Request, $middlewares, $this->coreMiddleware);

执行路由处理函数

在 Hyperf\HttpServer\CoreMiddleware::process() 方法中，主要逻辑是根据 Dispatcher 对象的状态执行相应的动作。

  • 如果路由不存在，则抛出 NotFoundHttpException 异常。
  • 如果请求方式不正确，则抛出 MethodNotAllowedHttpException 异常。
  • 如果找到路由，则解析并执行绑定在该路由上的处理函数，然后返回响应对象。

以下代码展示了这部分的执行逻辑。

public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    ...
    /** @var Dispatched $dispatched */
    $dispatched = $request->getAttribute(Dispatched::class);
    // 根据 `Dispatcher` 对象的状态执行相应动作
    $response = match ($dispatched->status) {
        Dispatcher::NOT_FOUND => $this->handleNotFound($request),
        Dispatcher::METHOD_NOT_ALLOWED => $this->handleMethodNotAllowed($dispatched->params, $request),
        Dispatcher::FOUND => $this->handleFound($dispatched, $request),
        default => null,
    };
    ...
}

Hyperf 支持闭包和请求处理器两种方式设置路由的处理函数，以下是这两种方式的示例。

// 闭包  
Router::get('/hello-hyperf', function () {  
    return 'Hello Hyperf.';
});  
  
// 请求处理器，下面三种方式的任意一种都可以达到同样的效果  
Router::get('/hello-hyperf', 'App\Controller\IndexController::hello');  
Router::get('/hello-hyperf', 'App\Controller\IndexController@hello');  
Router::get('/hello-hyperf', [App\Controller\IndexController::class, 'hello']);

在 handleFound() 方法中，如果处理函数是闭包，则调用 parseClosureParameters() 方法解析闭包的参数，然后运行闭包。

if ($dispatched->handler->callback instanceof Closure) {    
    $parameters = $this->parseClosureParameters($dispatched->handler->callback, $dispatched->params);    
    $callback = $dispatched->handler->callback;    
    $response = $callback(...$parameters);
}

如果处理函数是请求处理器，则调用 prepareHandler() 方法解析出请求处理器中的控制器（Controller）和操作（Action），通过容器实例化出控制器对象，然后调用 parseMethodParameters() 方法解析操作方法的参数，最后运行该方法。

[$controller, $action] = $this->prepareHandler($dispatched->handler->callback);  
$controllerInstance = $this->container->get($controller);  
...  
$parameters = $this->parseMethodParameters($controller, $action, $dispatched->params);  
$response = $controllerInstance->{$action}(...$parameters);

处理函数执行完成后，如果返回的结果没有实现 ResponseInterface 接口，则调用 transferToResponse() 方法对其进行转换，最后返回响应对象。

if (! $response instanceof ResponseInterface) {  
    $response = $this->transferToResponse($response, $request);  
}  
return $response->withAddedHeader('Server', 'Hyperf');

发送响应内容

有了响应对象之后，就需要将响应内容发送给客户端，这部分工作通过调用 Hyperf\HttpServer\ResponseEmitter::emit() 方法完成。

// Send the Response to client.  
if (! isset($psr7Response) || ! $psr7Response instanceof ResponseInterface) {  
    return;
}  
if (isset($psr7Request) && $psr7Request->getMethod() === 'HEAD') {  
    $this->responseEmitter->emit($psr7Response, $response, false);  
} else {  
    $this->responseEmitter->emit($psr7Response, $response);  
}

在 emit() 方法中，将 PSR-7 响应对象中的响应头、Cookies 以及状态码等信息写入到 Swoole 的响应对象中。然后判断响应体是否为文件对象，如果是则调用 Swoole\Http\Response::sendfile() 方法将文件发送到客户端；否则调用 Swoole\Http\Response::end() 方法发送响应内容。

public function emit(ResponseInterface $response, mixed $connection, bool $withContent = true): void
{
    try {
        if (strtolower($connection->header['Upgrade'] ?? '') === 'websocket') {
            return;
        }
        // 将 PSR-7 响应对象的信息写入到 Swoole 的响应对象中
        $this->buildSwooleResponse($connection, $response);
        // 判断响应内容是否为文件
        $content = $response->getBody();
        if ($content instanceof FileInterface) {
            // 发送文件到客户端
            $connection->sendfile($content->getFilename());
            return;
        }
        // 发送响应内容
        if ($withContent) {
            $connection->end((string) $content);
        } else {
            $connection->end();
        }
    } catch (Throwable $exception) {
        $this->logger?->critical((string) $exception);
    }
}

最后，我们就能够在浏览器中看到响应内容了。

总结

在这篇文章中，我们了解了 Hyperf 处理 HTTP 请求的完整流程。希望这些内容能帮你更好地理解 Hyperf 的工作原理。

]]> 深入 Hyperf：HTTP 服务启动时发生了什么？ https://her-cat.com/posts/2023/05/15/what-happens-when-hyperf-http-server-starts/ Mon, 15 May 2023 23:34:06 +0800 https://her-cat.com/posts/2023/05/15/what-happens-when-hyperf-http-server-starts/ 在这篇文章中，我会从启动命令开始，给你介绍下 Hyperf 的 HTTP 服务是如何完成初始化并启动的。 当我们创建 Hyperf 项目之后，只需要在终端执行 php bin/hyperf.php start 启动命令，等上几秒钟，就可以看到终端输出的 Worker 进程已启动，HTTP 服务监听在 9501 端口的日志信息。

[INFO] Worker#3 started.
[INFO] Worker#1 started.
[INFO] Worker#2 started.
[INFO] Worker#0 started.
[INFO] HTTP Server listening at 0.0.0.0:9501

打开浏览器访问 http://127.0.0.1:9501，不出意外的话，页面会显示 Hello Hyperf，说明 HTTP 服务已经在工作了。那么这是怎么做到的呢？当我们执行启动命令后，Hyperf 是如何让 HTTP 服务启动的？

所以今天这篇文章我会从启动命令开始，给你介绍下 HTTP 服务是如何完成初始化并启动的。通过阅读这篇文章，你可以了解到以下内容：

  • Hyperf 启动时会做哪些初始化操作？
  • HTTP 服务启动时会做哪些初始化操作？
  • HTTP 服务初始化时有哪些关键配置项？

接下来，我们就从 Hyperf 的入口文件开始，了解启动 HTTP 服务的实现思路。

bin/hyperf.php 文件：Hyperf 的入口

在启动命令中，除了 PHP 可执行文件以外，有两个是我们要关注的重点：

  • bin/hyperf.php：Hyperf 的入口文件
  • start：启动命令的参数

先来看一下 bin/hyperf.php 文件，我将该文件的执行逻辑分成了四个阶段。

初始化项目配置信息

在这个阶段中，主要是通过调用一些 PHP 内置函数，完成 PHP 相关的配置初始化，比如运行内存大小限制、错误级别、时区等等。

我们需要注意下在这一阶段定义的两个常量： BASE_PATH 和 SWOOLE_HOOK_FLAGS。

  • BASE_PATH：保存的是 Hyperf 项目所在目录的完整路径，Hyperf 中很多操作都是基于该常量来定位目录和文件的路径。
  • SWOOLE_HOOK_FLAGS：Swoole 采用 Hook 原生 PHP 函数的方式实现协程客户端，该常量保存的是 Hook 的函数的范围，比如套接字、文件、curl 等等。SWOOLE_HOOK_ALL 表示 Hook 所有函数。

我们经常会在 Swoole 相关的资料文档中看到「一键协程化」技术，实际上指的就是在启用协程时传入 SWOOLE_HOOK_ALL 配置项，通过 Hook 所有函数，让项目中会发生 IO 阻塞的代码变成可以协程调度的异步 IO，即一键协程化。

初始化类加载器

在 Hyperf 中，我们可以使用注解减少一些繁琐的配置，还可以基于注解实现很多强大的功能。比如注解注入、AOP 面向切面编程、路由定义、权限控制等等。这些功能能够正常运行，其实都离不开类加载器在初始化过程中的准备工作。

在初始化类加载器过程中，主要会进行以下操作：

  • 收集注解使用信息并完成注解收集器的初始化。
  • 生成代理类，为实现 AOP 及 Inject 注解注入功能做准备工作。
  • 生成运行时缓存，提高框架启动速度。

初始化依赖注入容器

在这个阶段， Hyperf 会先读取预先定义好的依赖关系的配置信息，包括 config/autoload/dependencies.php 配置文件中用户自定义的依赖关系，以及各组件中通过 ConfigProvider 机制定义的依赖关系。将这些初始的依赖关系保存到依赖注入容器中，完成对容器的初始化。

初始化命令行应用

我们回过头来看一下启动命令，你会发现，实际上 Hyperf 本身就是一个命令行应用，而启动命令中的 start 不过是命令行应用的参数，也就是要执行的命令的名字。

在 Hyperf 中有很多内置的命令，比如 start、migrate、gen 等等，当然我们也可以根据自己的需求自定义命令。初始化命令行应用的过程，就是将这些 Hyperf 内置的命令、自定义的命令，注册到命令行应用中的过程。

初始化并启动 HTTP 服务

到了这里，Hyperf 的初始化工作就已经结束了，命令行应用就会开始对启动命令中的参数进行解析，通过参数找到在命令行应用中注册的命令并执行。参数 start 对应的命令类是 StartServer，你可以在 hyperf/server 组件中找到它。

在 StartServer 中，完成了对 HTTP 服务的初始化以及启动操作，包含检查运行环境、读取服务配置文件、初始化 HTTP 服务、启动 HTTP 服务四个步骤，下面我们来了解一下这些步骤中分别做了哪些事情。

检查运行环境

我们知道，Hyperf 目前使用 Swoole 作为底层框架，所以在启动的时候，会先检查是否安装了 Swoole 的扩展，然后再检查是否禁用了 Swoole 的函数短名（short function name），如果没有禁用，就会输出提示信息并终止程序的运行。

读取服务配置

在 Hyperf 中，我们使用 config/autoload/server.php 文件来配置服务信息，详细的字段说明可以查看 Hyperf 官方文档。

其中有两个字段需要注意，分别是 server.type 和 server.servers.type，很多人不太清楚这两个配置项的作用和区别，下面我们来了解一下。

Swoole 提供了异步和协程两种风格的服务端，下面是两者的不同之处。

  • 协程风格的服务端可以在运行时动态创建、销毁，而异步风格的服务端在启动后就不能再对它进行操作了。
  • 协程风格的服务端对连接的处理是在单独的协程中完成，与客户端的交互是顺序性的，而异步风格的服务端无法保证顺序性。

Hyperf 作为上层框架，当然要支持这两种风格的服务端，同时还要考虑到扩展性，方便后续接入其它风格的服务端。

所以 Hyperf 在设计之初做了一层抽象，定义了一个 ServerInterface 接口，在接口中定义了三个常量，作为服务类型的枚举值。用于在配置文件中通过 server.servers.type 配置项设置服务的类型。同时，还定义了构造函数、初始化、启动三个方法。

interface ServerInterface
{    
	// HTTP 服务  
    public const SERVER_HTTP = 1;    
    // Websocket 服务  
    public const SERVER_WEBSOCKET = 2;    
   // TCP 服务  
    public const SERVER_BASE = 3;    
   // 构造函数  
    public function __construct(ContainerInterface $container, LoggerInterface $logger, EventDispatcherInterface $dispatcher);    
   // 初始化  
    public function init(ServerConfig $config): ServerInterface;    
   // 启动  
    public function start(): void;
}

Hyperf 不仅实现了基于 Swoole 的两种风格的服务端，还实现了基于 Swow 的服务端。

  • Hyperf\Server\Server：异步风格的服务端，由 Swoole 提供底层支持。
  • Hyperf\Server\CoroutineServer：协程风格的服务端，由 Swoole 提供底层支持。
  • Hyperf\Server\SwowServer：协程风格的服务端，由 Swow 提供底层支持。

我们可以通过 server.type 配置项，来决定使用哪种风格的服务端用于运行各种类型的服务。当然，你也可以通过实现 ServerInterface 接口，自定义其它类型的服务端。

初始化 HTTP 服务

通过上面的内容你可以知道，在运行 Hyperf 的时候，只能使用一种服务端，但是可以运行多个不同类型的服务，比如 HTTP 服务、Websocket 服务等等。为了便于说明，我会使用异步风格服务端给你介绍初始化 HTTP 服务的过程。

初始化 HTTP 服务的操作，是在 ServerFactory::configure 方法中完成的，主要可以分为两个步骤。

  • 第一步，将配置信息解析成 ServerConfig 对象。

在这一步骤中，主要是将配置文件中数组形式的配置信息，解析成 ServerConfig 对象。

class ServerConfig implements Arrayable
{
    public function __construct(protected array $config = [])
    {
	    // 将各种类型的服务解析成 Port 对象
        $servers = [];
        foreach ($config['servers'] as $item) {
            $servers[] = Port::build($item);
        }

		// 将其它类型的配置都保存到对象中
        $this->setType($config['type'] ?? Server::class)
            ->setMode($config['mode'] ?? 0)
            ->setServers($servers)
            ->setProcesses($config['processes'] ?? [])
            ->setSettings($config['settings'] ?? [])
            ->setCallbacks($config['callbacks'] ?? []);
    }
}

当没有设置服务端的类型时，默认使用 Hyperf\Server\Server，即异步类型的服务端。

  • 第二步，调用 Hyperf\Server\Server::init 方法完成对 HTTP 服务的初始化。

在这一步骤中，会调用 ServerFactory::getServer 方法，根据 ServerConfig 对象中的 type 属性实例化出对应的服务端对象，即 Hyperf\Server\Server 对象。在 Hyperf\Server\Server 对象中，定义了一个 server 属性，用于保存 Swoole 异步风格服务器对象。在 Swoole 异步风格的服务端中，有以下三种类型的服务器：

  • Swoole\Server：TCP 服务器，是所有异步风格服务器的基类。
  • Swoole\Http\Server：HTTP 服务器。
  • Swoole\WebSocket\Server：WebSocket 服务器。

在 init 方法中，会根据 server.servers.type 配置项的值（即 ServerInterface 接口中的常量），实例化出相应的服务器对象，并保存到 server 属性中。

这里会有一个问题，在 Hyperf\Server\Server 对象中只有一个 server 属性，但是，在 server.servers 配置项中，我们可以配置多个不同类型的服务，那么是如何支持运行多个服务的呢？

这里就跟 Swoole 的服务器实现有关，Swoole 的异步风格服务器可以通过调用 addListener 方法监听多个端口，每个端口都可以设置不同的协议处理方式。这样就实现了一个服务器对象，同时运行多个不同类型的服务。

下面我们来看一下 init 方法的主要逻辑。

首先，在 init 方法中会先调用 ServerFactory::sortServers 方法，对需要启动的服务按照类型 Websocket、HTTP、TCP 的顺序进行排序。

然后，依次遍历这些服务，完成对每个服务的初始化。循环中包括两个分支：

  • 第一个分支对应了 server 属性未初始化的情况。 此时，会调用 makeServer 方法实例化出相应的服务器对象，然后为服务器对象注册事件回调函数，最后初始化服务器对象的配置信息。
  • 第二个分支对应了 server 属性已初始化的情况。 此时，会调用服务器对象的 addListener 方法，增加一个端口并返回子服务器对象，然后为子服务器对象注册事件回调函数，最后初始化子服务器对象的配置信息。

在 makeServer 方法中，会根据服务类型实例化出相应的服务器对象，下面代码展示了这部分的逻辑，你可以看下。

switch ($type) {  
    case ServerInterface::SERVER_HTTP:  
        return new Swoole\Http\Server($host, $port, $mode, $sockType);  
    case ServerInterface::SERVER_WEBSOCKET:  
        return new Swoole\WebSocket\Server($host, $port, $mode, $sockType);  
    case ServerInterface::SERVER_BASE:  
        return new Swoole\Server($host, $port, $mode, $sockType);  
}

Swoole 提供了很多事件，比如 workerStart 工作进程启动后的事件、request 收到请求后的事件，这些事件在 Hyperf\Server\Event 中都有相应的常量。

在 Hyperf 中，有三种事件回调函数的配置，分别是全局事件、服务事件、默认事件。

  • 全局事件：使用 server.callbacks 配置项设置全局的事件的回调函数。
  • 服务事件：使用 server.servers.callbacks 配置项为每一个服务单独设置事件的回调函数。
  • 默认事件：在 Hyperf\Server\Server 对象的 defaultCallbacks 方法中配置了一些默认的事件的回调函数。

这些配置优先级是：服务事件 > 全局事件 > 默认事件。下面的代码展示了注册事件的回调函数的核心逻辑。

// 按照优先级获取配置的所有事件及其回调函数
$callbacks = array_replace($this->defaultCallbacks(), $config->getCallbacks(), $callbacks);
foreach ($callbacks as $event => $callback) {
	// 非 Swoole 事件，直接跳过
    if (! Event::isSwooleEvent($event)) {
        continue;
    }
    ...
    // 为服务器对象注册该事件的回调函数
    $server->on($event, $callback);
}

启动 HTTP 服务

在启动 HTTP 服务之前，会执行以下代码设置一键协程化 Hook 的函数范围，swoole_hook_flags 函数的返回值就是 SWOOLE_HOOK_FLAGS 常量的值，即 SWOOLE_HOOK_ALL。

Coroutine::set(['hook_flags' => swoole_hook_flags()]);

接着会调用 ServerFactory::start 方法启动服务，在该方法中，直接调用 Hyperf\Server\Server 的 start 方法启动 Swoole 服务器。

当 Swoole 服务器启动后，会执行注册在服务器对象的 Event::ON_WORKER_START 事件的回调函数 WorkerStartCallback::onWorkerStart。

在 onWorkerStart 方法中，输出 Worker#{$workerId} started. 日志信息，并通过事件分发器分发 AfterWorkerStart 事件，在该事件的监听器 AfterWorkerStartListener 中，输出 HTTP Server listening at 0.0.0.0:9501 日志信息。

到这里，HTTP 服务就已经启动了。

总结

在这篇文章中，我们通过 bin/hyperf.php 文件，了解了 Hyperf 在初始化框架时会执行哪些操作。接着，又通过 StartServer 了解了 HTTP 服务在启动过程中的四个步骤。其中，HTTP 服务的初始化是整个启动过程中的关键步骤，你可以配合源码进一步了解 Hyperf 的设计和实现思路。

尽管本文的主题是 HTTP 服务，但实际上，无论是 WebSocket服务、TCP服务还是其他类型的服务，这些服务的启动过程与 HTTP 服务的启动过程大同小异。

因此，掌握 HTTP 服务的启动过程，不仅有助于你了解 HTTP 服务的运行细节，还有助于你了解 Hyperf 以及其它类型服务的运行细节。当你遇到问题时，可以按照启动过程中的步骤逐步检查，从而帮助你更快地解决问题。

]]> 一次 Hyperf 注解失效问题分析 https://her-cat.com/posts/2023/03/02/hyperf-annotation-failure-problem-analysis/ Thu, 02 Mar 2023 23:58:06 +0800 https://her-cat.com/posts/2023/03/02/hyperf-annotation-failure-problem-analysis/ 本文讲述了我排查「Hyperf 注解失效」问题的过程，整个排查过程看似一气呵成，但实际上要曲折得多，甚至一度觉得这是个玄学问题。 问题环境 
PHP: 8.0.13
Swoole: 4.6.2
Hyperf: 2.2.33
运行环境: Docker Desktop on WSL2

问题背景

有同事说我之前使用注解实现的某个功能有问题，具体表现就是有部分使用了注解的类没有被 Hyperf 收集到注解收集器中，导致出现了不符合预期的结果。

由于这个功能已经运行了一段时间，并且我在自己的电脑（Mac）上测试是正常的，找另外一个跟他同样使用 Windows + Docker 开发的同事进行测试也是正常的，所以可以排除业务代码和环境的问题。

简化后的代码如下：

#[Attribute(Attribute::TARGET_CLASS)]  
class CustomAnnotation extends AbstractAnnotation
{
}  
  
#[CustomAnnotation]  
class Foo
{  
}  
  
#[CustomAnnotation]  
class Bar
{  
}

在上面的代码中，定义了一个注解类 CustomAnnotation，并且在两个类上使用了这个注解。期望的结果是 Foo 和 Bar 都能够被 Hyperf 收集到注解收集器中，但实际上只有 Foo 被收集到了。

Foo 和 Bar 分别在不同的文件中，但是都在同一个目录下，该目录下的文件数量有 60+。

于是我俩开始在他的电脑上排查是不是 Hyperf 的问题。

源码分析

在 Hyperf 启动时， ClassLoader 类加载器会扫描项目中所有的类文件，并将元数据（注解与类之间的关系）收集到相应的注解收集器中，如果没有自定义注解收集器，则默认统一收集到 Hyperf\Di\Annotation\AnnotationCollector 类中。

下面是完成收集注解的主要逻辑：

  • 使用 symfony/finder 组件提供的 Finder 类遍历指定目录下所有的 PHP 类文件。
  • 通过反射读取每个文件中的类及其属性、方法上使用的注解。
  • 依次检查这些注解是否实现了 Hyperf\Di\Annotation\AnnotationInterface 接口，该接口定义了三个方法分别用于收集类、方法、属性的元数据。
  • 如果注解实现了该接口，根据注解使用位置调用相应的方法将其收集到注解收集器中。

完成收集后，我们就能使用注解收集器提供的静态方法的获取对应的元数据用于实现一些自定义的逻辑和功能。

第一步就是先检查类文件是否被 Finder 类读取到了，这部分的逻辑在 ReflectionManager::getAllClasses() 静态方法中。

public static function getAllClasses(array $paths): array  
{  
    $finder = new Finder();  
    // 设置读取指定目录下的 PHP 文件
    $finder->files()->in($paths)->name('*.php');  
    $parser = new Ast();  
  
    $reflectionClasses = [];  
    foreach ($finder as $file) {  
        try {  
	        // 解析文件内容获取类名称
            $stmts = $parser->parse($file->getContents());  
            if (! $className = $parser->parseClassByStmts($stmts)) {
	            // 没获取到说明没有定义类
                continue;  
            }
            $reflectionClasses[$className] = static::reflectClass($className);  
        } catch (\Throwable) {  
        }    
    }    
    return $reflectionClasses;  
}

将获取目录下文件的这段代码提出来单独进行测试。由于 Finder 类实现了 IteratorAggregate 接口，所以在上面的代码中可以直接对 Finder 类进行遍历，也可以使用 iterator_to_array() 函数直接获取迭代器的结果。

$finder = new Finder();  
// 设置读取指定目录下的 PHP 文件
$finder->files()->in('出现问题的目录路径')->name('*.php'); 
var_dump(iterator_to_array($finder));

通过观察打印的结果就发现了问题所在：没有读取到 Bar 的类文件。

当时就在想，这么流行的一个组件包总不能出现这么低级的 Bug 吧？抱着怀疑的心态继续分析 Finder 类实现迭代器的代码，最后将问题定位到了 PHP 内置的 RecursiveDirectoryIterator 类上，Finder 类实际上就是对 PHP 的这些类做了一层封装。

RecursiveDirectoryIterator 提供了一个用于递归迭代文件系统目录的功能，用这个类再次进行上面的测试，依然没有读取到 Bar 的类文件。

$iter = new RecursiveDirectoryIterator('出现问题的目录路径');
var_dump(iterator_to_array($iter));

于是，我又一次陷入了怀疑中，难道 PHP 实现的这个类有问题？还得继续看 PHP 的源码？我在犹豫了一会后打开了 Google，抱着肯定有人也遇到过这个问题的想法输入了「RecursiveDirectoryIterator bug」，按下回车，在短暂的页面加载后…

嘿，还真有人已经遇到过这个问题。

真相大白

在前几条搜索结果中，赫然发现有人在 PHP 官方的 Bug 系统反馈了这个问题：RecursiveDirectoryIterator returns incorrect results for Docker Desktop on WSL2，并贴心的附带了可以复现问题的代码。

下面是精简过后的复现代码。

$filesPath = __DIR__.'/files';  
  
if (! mkdir($filesPath) && ! is_dir($filesPath)) {  
    throw new \RuntimeException(sprintf('Directory "%s" was not created', 'files'));  
}  
  
$max = 1;  
$stop = 5000;  
  
// 生成测试文件，模拟目录中文件较多的情况  
foreach(range(1, $stop) as $index) {  
    $message = sprintf("creating %s\n", $index);  
    echo $message;  
    file_put_contents(__DIR__ . '/files/file' . $index, str_repeat('A', 100));  
}  
  
$iter = new \RecursiveDirectoryIterator($filesPath, FilesystemIterator::KEY_AS_PATHNAME|FilesystemIterator::CURRENT_AS_FILEINFO|FilesystemIterator::SKIP_DOTS);  
var_dump(iterator_count($iter));
// 打印出来的数字小于 5000 说明复现成功了

PHP 官方给出了回复：这是 WSL 的 Bug，并提供了相关的 issue：WSL2: Seek of directory entry by lseek does not work on v9fs。里面的实际输出跟我们发现这个问题时的打印结果几乎一模一样，感兴趣的可以去看看。

有人可能会问，lseek() 函数跟 RecursiveDirectoryIterator 类有什么关系吗 ？

当然有！将上面的代码保存到 test.php 文件，然后执行 strace php test.php 命令查看 PHP 代码的系统调用情况。

...省略其他部分...
openat(AT_FDCWD, "/home/ubuntu/files", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 4
fstat(4, {st_mode=S_IFDIR|0775, st_size=135168, ...}) = 0
brk(0x55d84733f000)                     = 0x55d84733f000
getdents(4, /* 1024 entries */, 32768)  = 32752
lseek(4, 0, SEEK_SET)                   = 0
getdents(4, /* 1024 entries */, 32768)  = 32752
getdents(4, /* 1024 entries */, 32768)  = 32768
getdents(4, /* 1024 entries */, 32768)  = 32768
getdents(4, /* 1024 entries */, 32768)  = 32768
getdents(4, /* 906 entries */, 32768)   = 28992
getdents(4, /* 0 entries */, 32768)     = 0
write(1, "int(5000)\n", 10int(5000)
)             = 10
close(3)                                = 0
close(4)                                = 0
...省略其他部分...

可以看到，RecursiveDirectoryIterator 类在底层中调用了 lseek() 函数，它的作用是设置文件偏移量。lseek(4, 0, SEEK_SET) 表示将文件偏移量设置为 0，即文件开头的位置，该函数无法工作会导致下次操作依然使用的是原来的文件偏移量。

Linux 中万物皆为文件，包括目录。

用 PHP 代码来举个例子，这里使用 PHP 的 rewinddir() 函数代替 lseek() 函数，实际上底层调用的还是 lseek() 函数。

$dh = opendir(__DIR__ . '/files');  
  
echo '开始读取目录中的所有文件:' . PHP_EOL;  
while (($file = readdir($dh)) !== false) {  
    echo 'filename:' . $file . PHP_EOL;  
}
  
echo '再次读取目录中的所有文件:' . PHP_EOL;  
// 这时文件偏移量已经到达文件的末尾，再次读取目录将不会有任何输出，模拟 lseek() 函数无法工作的情况 
while (($file = readdir($dh)) !== false) {  
    echo 'filename:' . $file . PHP_EOL;  
}  
  
// 将文件偏移量重置到文件的开头  
rewinddir($dh);  
  
echo '重置偏移量后读取目录中的所有文件:' . PHP_EOL;  
// 与第一次读取的结果相同，模拟 lseek() 函数正常工作的情况
while (($file = readdir($dh)) !== false) {
    echo 'filename:' . $file . PHP_EOL;  
}  
  
closedir($dh);

在 WSL2 以外的系统中运行以上代码，可以得到与预期一致的结果。那么在 WSL2 中运行的结果是什么？

解决问题

当然，最好是 WSL 官方能够修复这个问题，但是从有人提出这个问题到现在已经快三年了依然没有被解决的情况来看，不知道得等到猴年马月。

提问的作者也给出了一种解决方案，开启 Hyper V。但是经过测试后发现开启 Hyper V 依然会出现这个问题，所以最后直接从 WSL2 回滚到 WSL1，从另一种「根本上」解决这个问题。

总结

等等，文章开头不是说已经排除是环境的问题了吗？怎么最后又是环境的问题了？

是的，这是由于我当时并没有问清楚，只是确认了另一个同事是用 Docker 运行的，我怎么也没想到他是本地运行了个虚拟机，然后在虚拟机里面运行 Docker…

当然，后面的源码分析也不是一点作用都没有，至少将问题的范围从 Hyperf 框架缩小到了 Finder 类，再到 RecursiveDirectoryIterator 类。否则直接 Google 搜索「Hyperf 注解失效」是很难找到正确答案的。

在这篇文章中，讲述了我排查「Hyperf 注解失效」问题的过程，整个排查过程看似一气呵成，但实际上要曲折得多，甚至一度觉得这是个玄学问题。

最后，没有 Bug 的程序是不存在的，不要过度迷信那些看似很可靠的系统。

]]> 译｜PHP 7 新的 Hashtable 实现 https://her-cat.com/posts/2022/10/31/php7-hashtable-implementation/ Mon, 31 Oct 2022 23:45:20 +0800 https://her-cat.com/posts/2022/10/31/php7-hashtable-implementation/ <p>大约三年前，我写了一篇分析 PHP 5 中<a href="https://www.npopov.com/2011/12/12/How-big-are-PHP-arrays-really-Hint-BIG.html">数组的内存使用情况</a>的文章。即将到来的 PHP 7 作为我工作的一部分，我重点关注于优化数据结构的大小以及内存分配上，为此重写了 Zend 引擎的大部分的内容。在这篇文章中，我将对新的 HashTable 实现进行概述，并说明为什么它比以前的实现更高效。</p> 大约三年前，我写了一篇分析 PHP 5 中数组的内存使用情况的文章。即将到来的 PHP 7 作为我工作的一部分，我重点关注于优化数据结构的大小以及内存分配上，为此重写了 Zend 引擎的大部分的内容。在这篇文章中，我将对新的 HashTable 实现进行概述，并说明为什么它比以前的实现更高效。

为了测量内存利用率，我将会使用下面的脚本创建一个包含 100000 个不同整数的数组：

$startMemory = memory_get_usage();
$array = range(1, 100000);
echo memory_get_usage() - $startMemory, " bytes\n";

下面这张表格展示了使用 PHP 5.6 和 PHP 7 在 32 位和 64 位系统上的内存使用情况：

        |   32 bit |    64 bit
------------------------------
PHP 5.6 | 7.37 MiB | 13.97 MiB
------------------------------
PHP 7.0 | 3.00 MiB |  4.00 MiB

可以看到，PHP 7 中的数组在 32 位上使用的内存要比 PHP 5.6 少 2.5 倍，在 64 位（LP64）上要少 3.5 倍，这是相当可观的性能提升。

Hashtable 介绍

从本质上讲，PHP 的数组是有序字典，即一个表示键/值对的有序列表，其中键/值映射是使用 Hashtable 实现的。

Hashtable 是一种非常常见的数据结构，它本质上解决了计算机只能直接表示连续的整数索引数组的问题，而程序员往往希望使用字符串或其它复杂类型作为键。

Hashtable 背后的概念非常简单：字符串通过哈希函数（hash function）处理后，哈希函数会返回一个整数（哈希值），然后将这个整数作为「普通」数组的索引。这里有一个问题，两个不同的字符串的可以产生相同的哈希值，因为字符串的大小几乎是无限制的，而哈希值则受到整数大小的限制。因此，HashTable 需要实现某种冲突解决机制。

冲突解决机制主要有两种：开放寻址法，如果发生哈希冲突，元素将被存储在不同的索引中；拉链法，所有哈希值相同的元素被存储在一个链表中。PHP 使用的是第二种。

通常情况下，Hashtable 中的元素是没有明确的顺序的。元素在底层数组中的存储顺序取决于哈希函数（hash function），并且非常的随机。但是这种行为与 PHP 数组的语义不一致：如果你遍历一个 PHP 数组，你将会按照元素的插入顺序取回元素。这意味着 PHP 的 Hashtable 实现必须支持一种额外的机制来记录数组元素的顺序。

旧的 Hashtable 实现

在这里，我只对旧的 Hashtable 实现做一个简短的概述，更全面的解释请看《PHP 内部实现》书籍中的 Hashtable 章节。

下面这张图从高层次的视角展示了 PHP 5 的 Hashtable 实现。

「冲突解决机制」链表中的元素被称为「bucket」，每一个 bucket 都是单独分配的。上面的图片中省略了这些 bucket 中存储的实际值（只展示了键）。值被存储在单独分配的 zval 结构体中，其大小为 16 字节（32 位）或 24 字节（64 位）。

上面的图片中没有展示的另一点是，冲突解决机制链表实际上是一个双向链表（使元素的删除变得简单）。除了冲突解决机制链表以外，Hashtable 还有另一个双向链表用来存储数组元素的顺序。对于按照顺序包含 “a”、“b”、“c” 的数组，该链表可能如下所示：

那么，为什么旧的 Hashtable 结构体在内存使用和性能方面都如此低效？有以下几个主要因素：

  • bucket 需要单独分配。分配的速度非常慢，并且还需要 8/16 字节的分配开销。单独分配意味着 bucket 在内存中会更加分散，从而会降低缓存的效率。
  • zval 也需要单独分配。同样，这也是很慢的，而且会产生额外的 header 开销。另外这需要每个 bucket 都保存一个指向 zval 的指针。因为旧的实现过于考虑通用性，所以实际上不只需要一个指针，而是两个指针。
  • 两个双向链表导致每个 bucket 总共需要 4 个指针。仅此就已经占用了 16/32 字节。此外，遍历链表是一种非常缓存不友好（cache-unfriendly）的操作。

新的 Hashtable 实现试图解决（或者至少是改善）这些问题。

新的 zval 实现

在讨论新的 Hashtable 之前，我想快速地介绍一下新的 zval 结构体，并强调它与旧结构体的区别。zval 结构体定义如下：

struct _zval_struct {
	zend_value value;
	union {
		struct {
			ZEND_ENDIAN_LOHI_4(
				zend_uchar type,
				zend_uchar type_flags,
				zend_uchar const_flags,
				zend_uchar reserved)
		} v;
		uint32_t type_info;
	} u1;
	union {
		uint32_t var_flags;
		uint32_t next;       /* 哈希冲突链表 */
		uint32_t cache_slot; /* 缓存槽 */
		uint32_t lineno;     /* 行号（用于 ast 节点） */
	} u2;
};

你可以忽略这个定义中的 ZEND_ENDIAN_LOHI_4 宏，它只是为了确保在具有不同字节序的机器上有一个可预测的内存布局。

zval 结构体有三个部分：第一个成员是 value。zend_value 联合体的大小为 8 字节，它可以存储不同类型的值，包括整数、字符串、数组等等。实际存储的内容取决于 zval 的类型。

第二部分是 4 个字节大小的 type_info，包括实际的类型（如 IS_STRING 或 IS_ARRAY），以及一些提供给该类型信息的附加标志。例如，如果 zval 存储的是一个对象，那么类型标志会说它是一个非常量（non-constant）、引用计数（refcounted）、垃圾回收（garbage-collectible）、不可复制（non-copying）的类型。

zval 结构体的最后 4 个字节通常是未使用的（它实际上只是显式填充，否则编译器会自动引入这种填充，即内存对齐）。然而在特殊情况下，这块空间被用来存储一些额外的信息。例如，AST 节点用它来存储行号，VM 常量用它来存储缓存槽索引，Hashtable 用它来存储冲突解决机制链表中的下一个元素。最后一部分对我们很重要。

如果你将其与之前的 zval 实现相比较，有一个区别特别明显：新的 zval 结构体不再存储 refcount。这背后的原因是，zval 本身不再被单独分配。相反，zval 直接嵌入到存储它的东西中（例如 Hashtable 的 bucket）。

虽然 zval 本身不再存储 refcount，但是字符串、数组、对象和资源这些复杂的数据类型仍然可以使用它。实际上，新的 zval 设计已经将 refcount（以及循环收集器的信息）移动到了数组、对象等复杂类型中。这种做法有很多优点，其中一部分优点如下：

  • zval 存储简单值（例如布尔值、整数或浮点数）不再需要任何分配。因此，通过避免不必要的分配和释放以及提高缓存本地性，这节省了分配头开销并提高了性能。
  • zval 存储简单值时，不需要存储 refcount 和垃圾回收根缓冲区（GC root buffer）。
  • 我们需要避免双重引用计数。例如，之前的对象使用了 zval 的 refcount，又使用了一个额外的对象 refcount，这对于支持按对象传递的语义来说是必须的。
  • 由于现在所有复杂的值都嵌入了 refcount，它们可以独立于 zval 机制而被共享。特别是现在还可以共享字符串。这对 Hashtable 的实现很重要，因为它不再需要复制 non-interned 字符串的键。

新的 Hashtable 实现

在所有前期准备工作结束后，我们终于可以看看 PHP 7 所使用的新的 Hashtable 实现。让我们先来看一下 bucket 的结构体：

typedef struct _Bucket {
	zend_ulong        h;
	zend_string      *key;
	zval              val;
} Bucket;

bucket 是 Hashtable 中的一个条目。它包含了你所期望的东西：哈希值 h，字符串键 key 和 zval 值 val。当键为整数时，整数会被存储在 h 中（在这种情况下，键和哈希值是相同的），并且成员 key 将会是 NULL。

如你所见，zval 直接嵌入到了 bucket 结构体中，因此它不需要单独分配，也就不会产生分配带来的开销。

Hashtable 的结构更加有趣：

typedef struct _HashTable {
	uint32_t          nTableSize;
	uint32_t          nTableMask;
	uint32_t          nNumUsed;
	uint32_t          nNumOfElements;
	zend_long         nNextFreeElement;
	Bucket           *arData;
	uint32_t         *arHash;
	dtor_func_t       pDestructor;
	uint32_t          nInternalPointer;
	union {
		struct {
			ZEND_ENDIAN_LOHI_3(
				zend_uchar    flags,
				zend_uchar    nApplyCount,
				uint16_t      reserve)
		} v;
		uint32_t flags;
	} u;
} HashTable;

bucket（即数组元素）存储在 arData 数组中。该数组的以 2 次方幂进行分配，数组大小存储在 nTableSize 中（最小值为 8）。元素的实际数量存储在 nNumOfElements 中。注意，这个数组直接包含 Bucket 结构体。以前我们使用一个指向单独分配的 bucket 的指针数组，这意味着我们需要执行更多次的分配和释放，必须要承担分配带来的开销，还要存维护额外的指针。

元素的顺序

arData 数组按照插入顺序存储元素。所以第一个数组元素将会被存储在 arData[0] 中，第二个存储在 arData[1] 中等等。任何时候都与所使用的键无关，只取决于插入的顺序。

因此，如果在 Hashtable 中存储 5 个元素，将使用插槽 arData[0] 到 arData[4]，下一个空闲的插槽是 arData[5]。我们使用 nNumUsed 来记录这个数字。你可能会问：为什么我们要单独存储它，它和 nNumOfElements 不是一样的吗？

是的，但是只有在只执行插入操作的情况下，它们会是一样的。如果从 Hashtable 中删除了一个元素，我们显然不想移动 arData 中出现在被删除元素之后的所有元素，以便再次拥有一个连续的数组。相反，我们只是使用 IS_UNDEF zval 类型来标记已删除的值。

举个例子，思考下面的代码：

$array = [
	'foo' => 0,
	'bar' => 1,
	0     => 2,
	'xyz' => 3,
	2     => 4
];
unset($array[0]);
unset($array['xyz']);

将会产生以下 arData 结构：

nTableSize     = 8
nNumOfElements = 3
nNumUsed       = 5

[0]: key="foo", val=int(0)
[1]: key="bar", val=int(1)
[2]: val=UNDEF
[3]: val=UNDEF
[4]: h=2, val=int(4)
[5]: NOT INITIALIZED
[6]: NOT INITIALIZED
[7]: NOT INITIALIZED

正如你所看到的，前五个 arData 元素已被使用，但是位置 2（键为 0）和位置 3（键为 'xyz'）的元素已被替换成了 IS_UNDEF，这是因为它们被 unset 了。现在这些元素的存在只是在浪费内存。但是，当 nNumUsed 等于 nTableSize 时，PHP 将尝试压缩 arData 数组，删除沿途添加的任何 UNDEF 条目。只有当所有的 bucket 都包含一个值时，arData 数组才会被重新分配到两倍的大小。

与 PHP 5.x 中使用的双向链表相比，维护数组顺序的新方法有几个优点。一个明显的优势是，我们为每个 bucket 节省了两个指针，相当于 8/16 字节，此外，这意味着数组的迭代看起来大致如下：

uint32_t i;
for (i = 0; i < ht->nNumUsed; ++i) {
	Bucket *b = &ht->arData[i];
	if (Z_ISUNDEF(b->val)) continue;

	// do stuff with bucket
}

这相当于对内存的线性扫描，这比遍历链表（在相对随机的内存地址之间来回）更高效。

目前的实现有一个问题，就是 arData 永远不会收缩（除非明确告诉它）。因此，如果你创建一个有几百万个元素的数组，之后将它们删除，那么这个数组仍然会占用大量的内存。如果利用率低于一定水平，我们也许应该把 arData 的大小减半。

HashTable 查找

到目前为止，我们只讨论了 PHP 数组如何表示顺序。实际上，Hashtable 的查找使用的是第二个数组 arHash，它由 uint32_t 类型的值组成。arHash 数组的大小与 arData 数组的大小相同（即 nTableSize），两者实际上都被分配在同一段连续的内存中。

从哈希函数（DJBX33A 是一种哈希算法，用于字符串类型的键）返回的哈希值是一个 32 位或 64 位无符号整数，这个整数值太大了，不能直接作为哈希数组的索引。我们首先需要使用模运算将其调整到 nTableSize 的大小范围内。我们使用 hash & (ht->nTableSize - 1) 代替 hash & ht->nTableSize，如果大小是 2 的幂也是一样的，不需要昂贵的整数除法运算。ht->nTableSize - 1 的值存储在 ht->nTableMask 中。

接下来，我们在哈希数组中查找索引 idx = ht->arHash[hash & ht->nTableMask]，这个索引（idx）相当于冲突解决机制链表的头。因此，ht->arData[idx] 是我们要检查的第一个条目。如果键和我们要找的一样，那么就完成了查找。

否则，我们必须继续检查冲突解决机制链表中的下一个元素。该元素的索引存储在 bucket->val.u2.next 中，它是 zval 结构体的最后 4 个字节，这些字节在这个上下文中具有特殊的意义。我们继续遍历这个链表（使用索引而不是指针），直到找到正确的 bucket，或者命中 INVALID_IDX，这意味着查找的键对应的元素不存在。

在代码中，查找机制如下所示：

zend_ulong h = zend_string_hash_val(key);
uint32_t idx = ht->arHash[h & ht->nTableMask];
while (idx != INVALID_IDX) {
	Bucket *b = &ht->arData[idx];
	if (b->h == h && zend_string_equals(b->key, key)) {
		return b;
	}
	idx = Z_NEXT(b->val); // b->val.u2.next
}
return NULL;

让我们考虑以下这种方法是如何改进以前的实现的：在 PHP 5.x 中，冲突解决机制使用基于指针的双向链表。使用 uint32_t 索引代替指针更好，因为它们的大小只有 64 位系统的一半。此外，在 4 个字节中，意味着我们可以将「next」链接嵌入到未使用的 zval 插槽中，因此我们基本上可以免费使用它。

我们现在使用的是单向链表，不再需要「prev」指针了。「prev」指针主要用于删除元素，因为当你删除某个元素的时候，你需要调整「prev」指针的「next」指针所指向的元素。但是，如果通过键删除元素，通过遍历冲突解决机制链表，你实际上已经知道前一个元素了。

少数情况下，删除发生在其它上下文中（例如，删除当前正在遍历的元素），将不得不遍历冲突解决机制链表找到前一个元素。但由于这是一个相当不重要的场景，我们更倾向于节省内存，而不是增加一个链表用于这种场景下查找前一个元素。

Packed Hashtable

PHP 中所有的数组都使用了 Hashtable。但是，在连续的、以整数为索引的数组（即真正的数组）这种比较常见的情况下，整个哈希过程没有多大意义。这就是为什么 PHP 7 引入了「Packed Hashtable」的概念。

在 Packed Hashtable 中，arHash 数组为 NULL，并且直接使用索引从 arData 中进行查找。如果你要找的键为 5，那么这个元素将位于 arData[5] 中，或者它根本就不存在。没有必要去遍历冲突解决机制链表。

注意，即使对于整数索引数组，PHP 也必须保持顺序。数组 [0 => 1, 1 => 2] 和 [1 => 2, 0 => 1] 是不一样的。Packed Hashtable 优化只有在键按升序排列时才起作用。它们之间可能有间隙（键不一定是连续的），但是它们要是呈递增趋势的。因此，如果元素以「错误」的顺序（例如反过来）插入到数组中，则不会使用 Packed Hashtable。

另外需要注意，Packed Hashtable 仍然存储大量无用的信息。例如，我们可以根据 bucket 的内存地址确定它的索引，因此 bucket->h 是多余的。bucket->key 的值始终为 NULL，因此它也只是在浪费内存。

我们保留这些无用的值以便于 bucket 使用相同的结构体，与是否使用 Packed Hashtable 无关。

这意味着迭代可以使用使用相同的 key。然而，将来我们可能会切换到「fully packed」的结构，如果可能的话，将会使用 zval 数组来实现。

空的 Hashtable

在 PHP 5.x 和 PHP 7 中，对于空的 Hashtable 都做了一些特殊处理。如果你创建一个空数组 []，很有可能你实际上不会插入任何元素。因此，arrData/arHash 数组只有在第一个元素被插入到 Hashtable 时才会被分配。

为了避免在许多地方检查这种特殊情况，这里使用了一个小技巧：当 nTableSize 被设置为提示的大小或默认值 8 时，nTableMask 被设置为 0（通常为 nTableSize - 1）。这意味着 hash & ht->nTableMask 的结果总是为 0。

因此，这种情况下的 arHash 数组只需要有一个包含 INVALID_IDX 值的元素（索引为 0），这个特殊数组被称为 uninitialized_bucket，是静态分配的。当执行查找时，我们总是找到 INVALID_IDX 值，这意味着没有找到键（这正是空数组所需要的）。

内存利用率

这一节将说明 PHP 7 中 Hashtable 实现的最重要的几个方面。首先让我们总结一下为什么新的实现使用较少的内存。在这里，我只使用 64 位系统的数字，并且只关注每个元素的大小，忽略 Hashtable 结构体（从渐进的角度看，它的意义不大）。

在 PHP 5.x 中，每个元素需要高达 144 个字节。在 PHP 7 中，这个值降到了 36 个字节，对于 Packed Hashtable 来说这个值是 32 字节。下面这些就是导致这戏的差异的原因：

  • zval 不是单独分配的，所以我们节省了 16 个字节的分配开销。
  • bucket 不是单独分配的，因此我们节省了另外 16 个字节的分配开销。
  • 对于简单的值，zval 比原来要小 16 个字节。
  • 不再为了保持元素的顺序而需要 16 个字节维护双向链表，并且这个顺序是隐式的。
  • 冲突解决机制链表限制是单向链表，节省了 8 个字节。此外，它现在是一个索引列表，索引被嵌入到了 zval 中，所以实际上我们又节省了 8 个字节。
  • 由于 zval 被直接嵌入到 bucket 中，我们不再需要存储一个指向它的指针。由于以前实现的细节问题，我们实际上又节省了两个指针，这又是 16 个字节。
  • bucket 不再存储键的长度，这又节省了 8 个字节。然而，如果键实际上是一个字符串而不是整数，那么长度仍然需要存储在 zend_string 结构体中。在这种情况下，无非准确的估算内存使用情况，因为 zend_string 结构体是共享的，对于以前的 Hashtable 来说，如果字符串是非内部（non-interned）的，则需要拷贝字符串。
  • 数组包含了冲突解决机制链表的头（基于索引的 head），因此每个元素可以节省 4 个字节。对于压缩数组（Packed Hashtable）来说，根本不需要冲突解决机制链表，在这种情况下，我们又节省了 4 个字节。

然而，上面的总结只是为了更清楚地说明新的 Hashtable 在哪些方面比旧的实现要好。首先，新的 Hashtable 大量的使用了嵌入式（而不是单独分配的）结构体。这会产生什么负面影响吗？

如果你仔细观察本文开头的实际测量结果，你会发现 PHP 7 在 64 位系统上，一个有 100000 个元素的数组占用了 4.00 MiB 的内存。在这种情况下，我们处理的是一个压缩数组（Packed Hashtable），实际上我们预期占用的内存应该是 32 * 100000 = 3.05 MiB。导致这个差异的原因是，在为数组分配内存时，总是以 2 次方幂进行分配。所以当数组包含 100000 个元素时，nTableSize 的值将会是 2 ^ 17 = 131072，最终会分配的内存是 32 * 131072（也就是 4.00 MiB）。

当然，以前的 Hashtable 实现也是使用 2 次方幂进行分配。但是，它只用这种方式分配了一个 bucket 指针数组（其中每个指针是 8 字节）。其它的都是按需分配的。所以在 PHP 7 中，我们浪费了 32 * 31072（0.95 MiB）未使用的内存，而在 PHP 5.x 中，我们只浪费了 8 * 31072（0.24 MiB）。

另一个需要考虑的问题是，如果数组中存储的所有值都不相同，会发生什么情况。为了简单起见，我们假设数组中所有的值都是相同的。因此，我们使用 array_fill 函数替换原本的 range 函数：

$startMemory = memory_get_usage();
$array = array_fill(0, 100000, 42);
echo memory_get_usage() - $startMemory, " bytes\n";

测试的结果如下：

        |   32 bit |    64 bit
------------------------------
PHP 5.6 | 4.70 MiB |  9.39 MiB
------------------------------
PHP 7.0 | 3.00 MiB |  4.00 MiB

正如你所看到的，在 PHP 7 中，内存使用情况与 range 的结果一致。由于所有的 zval 都是单独分配的，所以测试结果不可能是不一样的。另一方面，在 PHP 5.x 中，内存使用情况明显降低，这是因为所有的值只使用一个 zval。因此，虽然我们在 PHP 7 上仍然有一些进步，但是现在差距变小了。

一旦我们考虑到字符串键（可能是共享的或非共享的，又或者是非内部的）和复杂值的时候，事情就变得更加复杂了。重点在于 PHP 7 中的数组比 PHP 5.x 占用的内存要少很多，但是在很多情况下，引言中的数字可能过于乐观。

性能

我们已经讨论了很多关于内存使用情况的内容了，所以让我们转到下一个话题，性能。phpng 项目的最终目的不是为了改善内存的使用情况，而是提高性能。内存利用率的提高只是一种手段，因为更少的内存能够提高的 CPU 缓存利用率，从而带来更好的性能。

当然，还有很多其它原因导致新的实现会这么快：首先，减少了内存分配的次数。不管数组元素的值是否共享，我们都为每个元素节省了两次内存分配。内存分配是相当昂贵的操作，这对于性能的提升非常重要。

尤其是现在的数组遍历对缓存更加友好（ cache-friendly），因为它现在是对内存进行线性遍历，而不是随机访问（random-access）的链表遍历。

关于性能的话题可能还有很多可以说的，但本文主要的重点是内存的使用情况，所以我不会在这里进一步详述。

总结

就 Hashtable 的实现而言，PHP 7 无疑是向前迈进了一大步，很多无用的开销现在都已经被解决了。

因此，问题是：接下来我们该怎么办？在前面我已经提到的一个想法是，在整数键呈递增的情况下使用「fully packed」结构，这意味着将使用一个普通的 zval 数组实现，这是我们在不开始专门研究统一类型数组的情况下所能做到的最好的事情。

也许还有别的方向可以去尝试一下。例如，将哈希冲突解决机制从拉链法改成开放寻址法（例如使用 Robin Hood probing），在内存使用（没有冲突解决机制链表）和性能（更好的缓存效率，取决于算法的细节）方面都可能会更好。然而，开放寻址法相对来说很难跟保持数组元素顺序的需求结合起来，所以这个想法在实际情况中并不可行。

另一个想法是将 bucket 结构体中的 h 和 key 字段组合起来。整数键只使用 h 字段，字符串键也会在 key 中存储哈希值。然而，这可能会对性能产生不利的影响，因为获取哈希值将需要额外的内存间接寻址。

最后我想说的是，PHP 7 不仅改进了 Hashtable 的内部实现，而且还改进了相关的调用 API。在此之前，我经常不得不查看如何使用 zend_hash_find 这样简单的操作，特别是需要多少个间接级别（提示：3 个）。在 PHP 7 中，只需要编写 zend_hash_find(ht, key)，就可以得到一个 zval *。总的来说，我发现为 PHP 7 编写扩展程序变得更加愉快了。

希望我能够为你提供一些对于 PHP 7 的 Hashtable 内部实现的见解。也许我还会写一篇关于 zval 的后续文章。我已经在这篇文章中提到了一些不同之处，但关于这个话题还有很多可以说的。

原文：PHP’s new hashtable implementation

]]> Yar 源码阅读笔记：RPC 服务端 https://her-cat.com/posts/2022/01/18/yar-internals-server/ Tue, 18 Jan 2022 17:35:06 +0800 https://her-cat.com/posts/2022/01/18/yar-internals-server/ Yar 服务端处理客户端请求的步骤：解析请求数据、执行被调用方法、返回响应结果。 前言

在前面的文章中介绍了 Yar 客户端以及相关模块的实现，弄清楚了客户端的远程调用是如何发送出去的、发送的内容是什么、以及如何处理响应结果。

今天我们就来看看 Yar 服务端是如何处理客户端请求的。

服务端的实现

在开篇的服务端示例中可以看到，Yar_Server 有两个方法：构造函数和 handle 方法。

下面是 Yar_Server 的方法和属性的定义。

// source：yar_server.c

zend_function_entry yar_server_methods[] = {
    PHP_ME(yar_server, __construct, arginfo_service___construct, ZEND_ACC_PUBLIC|ZEND_ACC_CTOR|ZEND_ACC_FINAL)
    PHP_ME(yar_server, handle, arginfo_service_void, ZEND_ACC_PUBLIC)
    PHP_FE_END
};

YAR_STARTUP_FUNCTION(service) {
    zend_class_entry ce;

    INIT_CLASS_ENTRY(ce, "Yar_Server", yar_server_methods);
    yar_server_ce = zend_register_internal_class(&ce);
    zend_declare_property_null(yar_server_ce, ZEND_STRL("_executor"), ZEND_ACC_PROTECTED);

    return SUCCESS;
}

下面来看看这两个方法的实现。

构造函数

构造函数的作用是将需要对外提供服务的对象保存到 Yar_Server 的 _executor 中。处理客户端的请求时，就会执行该对象中被调用的方法。

// source：yar_server.c

PHP_METHOD(yar_server, __construct) {
    zval *obj;

    if (zend_parse_parameters_throw(ZEND_NUM_ARGS(), "o", &obj) == FAILURE) {
        return;
    }

    // 保存对象到 _executor 中
    zend_update_property(yar_server_ce, getThis(), "_executor", sizeof("_executor")-1, obj);
}

处理请求

在 handle 方法中，通过判断请求方式执行不同的逻辑。

  • 非 POST 请求：例如 GET 请求，输出 RPC 服务的 API 信息。
  • POST 请求：处理客户端的远程调用，执行被调用的方法，返回响应结果。
// source：yar_server.c

PHP_METHOD(yar_server, handle)
{
    // ...

    const char *method;
    zval *executor, rv;

    // 获取被调用的对象
    executor = zend_read_property(yar_server_ce, getThis(), ZEND_STRL("_executor"), 0, &rv);
    if (IS_OBJECT != Z_TYPE_P(executor)) {
        php_error_docref(NULL, E_WARNING, "executor is not a valid object");
        RETURN_FALSE;
    }

    // 判断请求方式，非 POST 请求则输出 API 信息
    method = SG(request_info).request_method;
    if (!method || strncasecmp(method, "POST", 4)) {
        // 检查是否开启了 expose_info 
        if (YAR_G(expose_info)) {
            php_yar_server_info(executor);
            RETURN_TRUE;
        } else {
            zend_throw_exception(yar_server_exception_ce, "server info is not allowed to access", YAR_ERR_FORBIDDEN);
            return;
        }
    }
    
    // 处理客户端的远程调用
    php_yar_server_handle(executor);

    RETURN_TRUE;
}

php_yar_server_info 函数的作用是输出 API 信息页面的 HTML 及被调用对象中所有 public 方法的信息。

// source：yar_server.c

static void php_yar_server_info(zval *obj) {
    char buf[1024];
    zend_class_entry *ce = Z_OBJCE_P(obj);

    // 输出 header 部分
    snprintf(buf, sizeof(buf), HTML_MARKUP_HEADER, ZSTR_VAL(ce->name));
    PHPWRITE(buf, strlen(buf));

    // 输出 css 和 javascript 部分
    PHPWRITE(HTML_MARKUP_CSS, sizeof(HTML_MARKUP_CSS) - 1);
    PHPWRITE(HTML_MARKUP_SCRIPT, sizeof(HTML_MARKUP_SCRIPT) - 1);

    // 输出网页标题
    snprintf(buf, sizeof(buf), HTML_MARKUP_TITLE, ZSTR_VAL(ce->name));
    PHPWRITE(buf, strlen(buf));

    // 读取并输出被调用对象的方法列表
    zend_hash_apply_with_argument(&ce->function_table, (apply_func_arg_t)php_yar_print_info, (void *)(ce));

    // 输出 footer 部分
    PHPWRITE(HTML_MARKUP_FOOTER, sizeof(HTML_MARKUP_FOOTER) - 1);
}

static int php_yar_print_info(zval *ptr, void *argument) /* {{{ */ {
    zend_function *f = Z_FUNC_P(ptr);

    // 判断是否为 public 方法
    if (f->common.fn_flags & ZEND_ACC_PUBLIC 
        && f->common.function_name && *(ZSTR_VAL(f->common.function_name)) != '_') {
        char *prototype = NULL;
        // 获取函数原型
        if ((prototype = php_yar_get_function_declaration(f))) {
            char *buf, *doc_comment = NULL;
            if (f->type == ZEND_USER_FUNCTION) {
                if (f->op_array.doc_comment != NULL) {
                    // 读取函数的 doc 注释
                    doc_comment = (char *)ZSTR_VAL(f->op_array.doc_comment);
                }
            }
            // 输出函数原型及注释
            spprintf(&buf, 0, HTML_MARKUP_ENTRY, prototype, doc_comment? doc_comment : "");
            efree(prototype);
            PHPWRITE(buf, strlen(buf));
            efree(buf);
        }
    }

    return ZEND_HASH_APPLY_KEEP;
}

下面继续看看 php_yar_server_handle 函数，该函数的主要逻辑如下：

  • 读取 HTTP 请求中 body 的内容。
  • 调用 php_yar_protocol_parse 函数解析读取到的内容。
  • 调用 php_yar_packager_unpack 函数对 payload 进行解码。
  • 调用 php_yar_request_unpack 函数解析请求数据。
  • 执行被调用的方法。
  • 返回响应结果。
// source：yar_server.c

static void php_yar_server_handle(zval *obj) /* {{{ */ {
    // ...

    // 读取 HTTP 请求 body 中的内容
    while (!php_stream_eof(s)) {
        len += php_stream_read(s, buf + len, sizeof(buf) - len);
        if (len == sizeof(buf) || raw_data.s) {
            smart_str_appendl(&raw_data, buf, len);
            len = 0;
        }
    }

    // 获取 body 中的内容及长度
    if (len) {
        payload = buf;
        payload_len = len;
    } else if (raw_data.s) {
        smart_str_0(&raw_data);
        payload = ZSTR_VAL(raw_data.s);
        payload_len = ZSTR_LEN(raw_data.s);
    } else {
        php_yar_error(response, YAR_ERR_PACKAGER, "empty request body");
        DEBUG_S("0: empty request '%s'");
        goto response_no_output;
    }

    // 解析 body 中的内容
    if (!(header = php_yar_protocol_parse(payload))) {
        php_yar_error(response, YAR_ERR_PACKAGER, "malformed request header '%.10s'", payload);
        DEBUG_S("0: malformed request '%s'", payload);
        goto response_no_output;
    }

    // 跳过 Yar 协议的头部信息
    payload += sizeof(yar_header_t);
    payload_len -= sizeof(yar_header_t);

    // 解码 payload 部分
    if (!(post_data = php_yar_packager_unpack(payload, payload_len, &err_msg, &ret))) {
        php_yar_error(response, YAR_ERR_PACKAGER, err_msg);
        efree(err_msg);
        goto response_no_output;
    }

    pkg_name = payload;

    // 解析请求数据
    request = php_yar_request_unpack(post_data);

    if (php_output_start_user(NULL, 0, PHP_OUTPUT_HANDLER_STDFLAGS) == FAILURE) {
        php_yar_error(response, YAR_ERR_OUTPUT, "start output buffer failed");
        goto response_no_output;
    }

    // 检查被调用方法是否存在
    if (!zend_hash_exists(&ce->function_table, method)) {
        zend_string_release(method);
        php_yar_error(response, YAR_ERR_REQUEST, "call to undefined api %s::%s()", ce->name, ZSTR_VAL(request->method));
        goto response;
    }

    zend_try {

        // 初始化被调用方法的参数
        func_params_ht = Z_ARRVAL(request->parameters);
        count = zend_hash_num_elements(func_params_ht);

        if (count) {
            int i = 0;
            func_params = safe_emalloc(sizeof(zval), count, 0);

            ZEND_HASH_FOREACH_VAL(func_params_ht, tmp_zval) {
                ZVAL_COPY(&func_params[i++], tmp_zval);
            } ZEND_HASH_FOREACH_END();
        } else {
            func_params = NULL;
        }

        ZVAL_STR(&func, request->method);

        // 执行被调用的方法
        if (FAILURE == call_user_function(NULL, obj, &func, &retval, count, func_params)) {
            if (count) {
                int i = 0;
                for (; i < count; i++) {
                    zval_ptr_dtor(&func_params[i]);
                }
                efree(func_params);
            }
            php_yar_error(response, YAR_ERR_REQUEST, "call to api %s::%s() failed", ce->name, request->method);
            goto response;
        }
        
        // 释放参数
        if (count) {
            int i = 0;
            for (; i < count; i++) {
                zval_ptr_dtor(&func_params[i]);
            }
            efree(func_params);
        }
    } zend_catch {
        bailout = 1;
    } zend_end_try();

    // 如果发生异常则响应异常信息
    if (EG(exception)) {
        zend_object *exception = EG(exception);
        php_yar_response_set_exception(response, exception);
        EG(exception) = NULL; /* exception may have __destruct will be called */
        OBJ_RELEASE(exception);
        zend_clear_exception();
    }

// 正常响应
response:
   
    // 获取输出到缓冲区的内容
    if (php_output_get_contents(&output) == FAILURE) {
        php_output_end();
        php_yar_error(response, YAR_ERR_OUTPUT, "unable to get ob content");
        goto response_no_output;
    }
    
    // 将缓冲区的内容保存到 response 的 out 中
    php_yar_response_alter_body(response, Z_STR(output), YAR_RESPONSE_REPLACE);

// 无输出响应
response_no_output:
    // 组装并输出响应内容
    php_yar_server_response(request, response, pkg_name);
    if (request) {
        // 释放请求对象
        php_yar_request_destroy(request);
    }

    // 释放响应对象
    php_yar_response_destroy(response);

    if (bailout) {
        zend_bailout();
    }

    return;
}

总结

在这篇文章中，介绍了 Yar 服务端是如何处理客户端请求的，主要是三个步骤：解析请求数据、执行被调用方法、返回响应结果。结合之前的文章就可以知道在一次远程调用的过程中，客户端、服务端都分别做了些什么。

]]> Yar 源码阅读笔记：客户端的并行调用 https://her-cat.com/posts/2022/01/14/yar-internals-client-concurrent-call/ Fri, 14 Jan 2022 19:50:08 +0800 https://her-cat.com/posts/2022/01/14/yar-internals-client-concurrent-call/ 主要介绍实现并行调用相关的数据结构，并通过 GDB 调试代码的方式展示并行调用运行的过程。 前言

在上一篇文章中，介绍了客户端同步调用的具体实现的，主要还是通过调用传输模块的相关函数，完成发送和接收远程调用的数据。

在调用多个远程方法时，同步调用是以串行的方式执行的，导致运行效率比较低，所以需要使用并行调用来提高调用多个远程方法的运行效率，减少整体运行的时间。

并行传输模块

yar_transport_multi_t

在数据传输模块中，我们提到了 yar_transport_multi_t *multi 就是用来实现并行调用的，先来看看该结构体的定义。

// source：yar_transport.h

// 并行传输器的工厂
typedef struct _yar_transport_multi {
    struct _yar_transport_multi_interface * (*init)();
} yar_transport_multi_t;

可以将 yar_transport_multi_t 看作是并行传输器的工厂，使用 init 函数创建并行传输器的实例，也就是为 _yar_transport_multi_interface 结构体分配内存，并初始化相关配置。

yar_transport_multi_interface_t

// source：yar_transport.h

// 并行传输器
typedef struct _yar_transport_multi_interface {
    void *data;
    int (*add)(struct _yar_transport_multi_interface *self,     yar_transport_interface_t *cp);
    int (*exec)(struct _yar_transport_multi_interface *self,     yar_concurrent_client_callback *callback);
    void (*close)(struct _yar_transport_multi_interface *self);
} yar_transport_multi_interface_t;

其实 yar_transport_multi_interface_t 结构体和 yar_transport_interface_t 结构体类似，都是用来定义在传输时使用的函数，下面是字段说明：

  • data：存储并行传输器的数据指针，指向 yar_curl_multi_data_t 结构体。
  • add：函数指针，将一个同步传输器（yar_transport_interface_t）实例中的数据存储到并行传输器中。
  • exec：函数指针，执行请求，将所有的同步传输器实例中的数据发送出去。
  • close：函数指针，释放相关资源。

从上面的说明可以看出来，并行传输器实际上是在管理多个同步传输器实例，先调用 add 函数将同步传输器实例存储到并行传输器中，然后通过 exec 函数将这些同步传输器实例中的数据发送出去，并对响应结果进行处理，最后调用 close 函数清理相关资源。

yar_curl_multi_data_t

虽然 yar_curl_multi_data_t 结构体的字段比较少，但是通过这个结构体，可以知道并行传输器是如何存储同步传输器实例的数据的。

// source：transports/curl.c

typedef struct _yar_curl_multi_data_t {
    CURLM *cm;
    yar_transport_interface_t *chs;
} yar_curl_multi_data_t;

cm 字段用来存储 curl 批处理实例的指针，chs 则是同步传输器的指针，同步传输器中 data 字段指向的结构体中有一个 next 字段，用来指向下一个同步传输器：

// source：transports/curl.c

typedef struct _yar_curl_data_t {
    // ...
    yar_transport_interface_t *next;
} yar_curl_data_t;

看到这里你应该就明白了，Yar 通过单链表的结构将所有的同步传输器实例串起来， yar_curl_multi_data_t 中的 chs 字段相当于头指针。

并行客户端

先来看看并行客户端的方法列表及属性。

// source：yar_client.c

    // 方法列表
    zend_function_entry yar_concurrent_client_methods[] = {
        PHP_ME(yar_concurrent_client, call, arginfo_client_async, ZEND_ACC_PUBLIC|ZEND_ACC_STATIC)
        PHP_ME(yar_concurrent_client, loop, arginfo_client_loop, ZEND_ACC_PUBLIC|ZEND_ACC_STATIC)
        PHP_ME(yar_concurrent_client, reset,arginfo_client_void, ZEND_ACC_PUBLIC|ZEND_ACC_STATIC)
        PHP_FE_END
    };

    INIT_CLASS_ENTRY(ce, "Yar_Concurrent_Client", yar_concurrent_client_methods);
    yar_concurrent_client_ce = zend_register_internal_class(&ce);
    // 声明并行客户端的属性
    zend_declare_property_null(yar_concurrent_client_ce, ZEND_STRL("_callstack"), ZEND_ACC_PROTECTED|ZEND_ACC_STATIC);
    zend_declare_property_null(yar_concurrent_client_ce, ZEND_STRL("_callback"), ZEND_ACC_PROTECTED|ZEND_ACC_STATIC);
    zend_declare_property_null(yar_concurrent_client_ce, ZEND_STRL("_error_callback"), ZEND_ACC_PROTECTED|ZEND_ACC_STATIC);
    zend_declare_property_bool(yar_concurrent_client_ce, ZEND_STRL("_start"), 0, ZEND_ACC_PROTECTED|ZEND_ACC_STATIC);

由此我们可以知道并行客户端大概长这样：

class {
    protected static $_callstack = null; // 存储每个调用的数据
    protected static $_callback = null; // 并行客户端的回调函数
    protected static $_error_callback = null; // 并行客户端的异常回调函数
    protected static $_start = false; // 是否已启动
    
    // 调用某个方法
    public static function call($uri, $method, $parameters = null, $callback = null, $error_callback = null, $options = array()) 
    {
        
    }
    
    // 执行调用并等待响应
    public static function loop($callback = null, $error_callback = null) 
    {
        
    }
    
    // 重置并行客户端
    public static function reset()
    {
        
    }
}

Yar 定义了 yar_call_data_t 结构体将 call 方法的参数存起来，当作远程调用的数据。

// source：yar_transport.h

typedef struct _yar_call_data {
    zend_long sequence;
    zend_string *uri;
    zend_string *method;
    zval callback;
    zval ecallback;
    zval parameters;
    zval options;
} yar_call_data_t;

在 PHP 中使用该结构体前，需要在 Yar 启动时向 PHP 注册该资源类型，同时传入析构函数，用于 PHP 释放该资源的时候调用。

YAR_STARTUP_FUNCTION(transport) {
    // ... 

    le_calldata = zend_register_list_destructors_ex(php_yar_calldata_dtor, NULL, "Yar Call Data", module_number);

    return SUCCESS;
}

zend_register_list_destructors_ex 函数会返回一个整数，表示注册的资源类型，在取回资源时需要用到该整数。

并行调用

这次我们使用 gdb 调试的方式，一步步的展示并行调用的过程，在此之前需要编译好 Yar，编译时记得关闭编译优化，并在 php.ini 中配置好扩展，然后启动开篇中的 Yar 服务端示例。

Yar_Concurrent_Client::call

在客户端的并行调用示例中，先调用了 call 方法，然后调用了 loop 方法，所以我们分别在这两个方法的上打断点。通过上面并行客户端的介绍可以知道，实现 call 方法的函数是 zim_yar_concurrent_client_call，我们在该函数上打断点即可。

$ gdb php
(gdb) b zim_yar_concurrent_client_call
Function "zim_yar_concurrent_client_call" not defined.
Make breakpoint pending on future shared library load? (y or [n]) y
Breakpoint 1 (zim_yar_concurrent_client_call) pending.
(gdb)

开始运行 PHP 并指定运行的 PHP 脚本。

(gdb) r concurrent_client.php
Starting program: /usr/bin/php concurrent_client.php
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Breakpoint 1, zim_yar_concurrent_client_call (
    execute_data=0x5555557de9ee <zend_restore_lexical_state+222>,
    return_value=0x555555a2b240 <language_scanner_globals>)
    at /home/vagrant/code/her-cat/yar/yar_client.c:645
645    PHP_METHOD(yar_concurrent_client, call) {
(gdb)

zim_yar_concurrent_client_call 函数作用是将 call 方法的参数组装为 yar_call_data_t 结构体，并存储到并行客户端的 _callstack 数组中，然后返回本次调用的序号。

// source：yar_client.c

PHP_METHOD(yar_concurrent_client, call) {
    zend_string *uri, *method;
    zend_string *name = NULL;
    zval *callstack, item, *status;
    zval *error_callback = NULL, *callback = NULL, *parameters = NULL, *options = NULL;
    yar_call_data_t *entry;

    // 解析 call 方法中的参数
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "SS|a!z!za",
                &uri, &method, &parameters, &callback, &error_callback, &options) == FAILURE) {
        return;
    }

    // 省略一些对参数校验的代码...

    
    // 校验并行客户端的状态
    status = zend_read_static_property(yar_concurrent_client_ce, ZEND_STRL("_start"), 0);
    if (UNEXPECTED(Z_TYPE_P(status) == IS_TRUE)) {
        php_error_docref(NULL, E_WARNING, "concurrent client has already started");
        RETURN_FALSE;
    }

    // 分配调用数据的内存
    entry = ecalloc(1, sizeof(yar_call_data_t));

    // 将参数赋值到调用数据上
    entry->uri = zend_string_copy(uri);
    entry->method = zend_string_copy(method);

    if (callback && !Z_ISNULL_P(callback)) {
        ZVAL_COPY(&entry->callback, callback);
    }
    if (error_callback && !Z_ISNULL_P(error_callback)) {
        ZVAL_COPY(&entry->ecallback, error_callback);
    }
    if (parameters && IS_ARRAY == Z_TYPE_P(parameters)) {
        ZVAL_COPY(&entry->parameters, parameters);
    }
    if (options && IS_ARRAY == Z_TYPE_P(options)) {
        ZVAL_COPY(&entry->options, options);
    }

    // 初始化调用栈数组
    callstack = zend_read_static_property(yar_concurrent_client_ce, ZEND_STRL("_callstack"), 0);
    if (Z_ISNULL_P(callstack)) {
        zval rv;
        array_init(&rv);
        zend_update_static_property(yar_concurrent_client_ce, ZEND_STRL("_callstack"), &rv);
        ZVAL_ARR(callstack, Z_ARRVAL(rv));
        Z_DELREF(rv);
    }

    // 将调用数据注册到 zend 中，并返回 zend_resouce 类型的数据
    ZVAL_RES(&item, zend_register_resource(entry, le_calldata));

    // 设置调用数据的序号
    entry->sequence = zend_hash_num_elements(Z_ARRVAL_P(callstack)) + 1;

    // 将 zend_resource 类型的调用数据存储到 callstack 中
    zend_hash_next_index_insert(Z_ARRVAL_P(callstack), &item);

    RETURN_LONG(entry->sequence);
}

让代码执行到最后一行，并打印 entry 中的数据。

(gdb) u 733
zim_yar_concurrent_client_call (execute_data=0x7ffff54130d0,
    return_value=0x7fffffffaa80)
    at /home/vagrant/code/her-cat/yar/yar_client.c:733
733        RETURN_LONG(entry->sequence);
(gdb) p *entry->uri.val@32
$5 = "http://127.0.0.1:3000/server.php"
(gdb) p *entry->method.val@5
$6 = "login"
(gdb) p entry->sequence
$7 = 1

Yar_Concurrent_Client::loop

先在 loop 方法上打断点，然后让代码执行到断点处。

(gdb) b zim_yar_concurrent_client_loop
Breakpoint 2 at 0x7ffff56e97f7: file /home/vagrant/code/her-cat/yar/yar_client.c, line 751.
(gdb) c
Continuing.

Breakpoint 1, zim_yar_concurrent_client_call (execute_data=0x7ffff54130d0, return_value=0x7fffffffaa80)
    at /home/vagrant/code/her-cat/yar/yar_client.c:645
645    PHP_METHOD(yar_concurrent_client, call) {
(gdb)

在 zim_yar_concurrent_client_loop 函数中，先校验 loop 方法的参数及并行客户端的运行状态，然后从并行客户端中读取 _callstack 数组，调用 php_yar_concurrent_client_handle 函数。

// source：yar_client.c

PHP_METHOD(yar_concurrent_client, loop) {
    zend_string *name = NULL;
    zval *callstack;
    zval *callback = NULL, *error_callback = NULL;
    zval *status;
    unsigned ret = 0;

    // 解析参数
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "|zz", &callback, &error_callback) == FAILURE) {
        return;
    }

    // 判断运行状态
    status = zend_read_static_property(yar_concurrent_client_ce, ZEND_STRL("_start"), 0);
    if (UNEXPECTED(Z_TYPE_P(status) == IS_TRUE)) {
        php_error_docref(NULL, E_WARNING, "concurrent client has already started");
        RETURN_FALSE;
    }
    
    // 省略一些对参数校验的代码...

    // 读取所有的调用数据
    callstack = zend_read_static_property(yar_concurrent_client_ce, ZEND_STRL("_callstack"), 0);
    if (Z_ISNULL_P(callstack) || zend_hash_num_elements(Z_ARRVAL_P(callstack)) == 0) {
        RETURN_TRUE;
    }

    // 更新为运行中的状态
    ZVAL_BOOL(status, 1);
    ret = php_yar_concurrent_client_handle(callstack);
    ZVAL_BOOL(status, 0);
    RETURN_BOOL(ret);
}

php_yar_concurrent_client_handle

让代码执行到调用 php_yar_concurrent_client_handle 的前一行，然后进入函数内部。

(gdb) u 801
zim_yar_concurrent_client_loop (execute_data=0x7ffff54130d0, return_value=0x7fffffffaa80)
    at /home/vagrant/code/her-cat/yar/yar_client.c:801
801        ZVAL_BOOL(status, 1);
(gdb) s
802        ret = php_yar_concurrent_client_handle(callstack);
(gdb) s
php_yar_concurrent_client_handle (callstack=0x0) at /home/vagrant/code/her-cat/yar/yar_client.c:456
456    int php_yar_concurrent_client_handle(zval *callstack) /* {{{ */ {
(gdb)

php_yar_concurrent_client_handle 函数的主要逻辑：

  • 遍历 callstack 数组
    • 为每一个调用数据创建同步传输器。
    • 分别调用同步传输器中的 open、send、calldata 等函数初始化调用请求。
    • 调用 multi->add 函数将这些同步传输器存储到并行调用器中。
  • 调用 multi->exec 函数将这些请求发送出去。
  • 收到响应结果后调用 php_yar_concurrent_client_callback 函数进行处理。
  • 最后调用 multi->close 函数释放相关资源。
// source：yar_client.c

int php_yar_concurrent_client_handle(zval *callstack) /* {{{ */ {
    char *msg;
    zval *calldata;
    yar_request_t *request;
    const yar_transport_t *factory;
    yar_transport_interface_t *transport;
    yar_transport_multi_interface_t *multi;

    // 获取 curl 传输器工厂实例
    factory = php_yar_transport_get(ZEND_STRL("curl"));
    // 创建并行传输器实例
    multi = factory->multi->init();

    // 遍历 callstack 数组
    ZEND_HASH_FOREACH_VAL(Z_ARRVAL_P(callstack), calldata) {
        yar_call_data_t *entry;
        long flags = 0;

        entry = (yar_call_data_t *)zend_fetch_resource(Z_RES_P(calldata), "Yar Call Data", le_calldata);

        if (!entry) {
            continue;
        }

        if (Z_ISUNDEF(entry->parameters)) {
            array_init(&entry->parameters);
        } 

        // 为每一个调用数据创建同步传输器
        transport = factory->init();

        if (!Z_ISUNDEF(entry->options)) {
            zval *flag = php_yar_client_get_opt(&entry->options, YAR_OPT_PERSISTENT);
            if (flag && (Z_TYPE_P(flag) == IS_TRUE || (Z_TYPE_P(flag) == IS_LONG && Z_LVAL_P(flag)))) {
                flags |= YAR_PROTOCOL_PERSISTENT;
            }
        }

        // 创建调用请求
        if (!(request = php_yar_request_instance(entry->method,
                        &entry->parameters, Z_ISUNDEF(entry->options)? NULL: & entry->options))) {
            transport->close(transport);
            factory->destroy(transport);
            return 0;
        }

        // 创建一个连接
        msg = (char*)&entry->options;
        if (!transport->open(transport, entry->uri, flags, &msg)) {
            php_yar_client_trigger_error(1, YAR_ERR_TRANSPORT, msg);
            transport->close(transport);
            factory->destroy(transport);
            efree(msg);
            return 0;
        }

        // 对请求数据进行编码、组装等操作，并将处理后的数据保存到连接中
        if (!transport->send(transport, request, &msg)) {
            php_yar_client_trigger_error(1, YAR_ERR_TRANSPORT, msg);
            transport->close(transport);
            factory->destroy(transport);
            efree(msg);
            return 0;
        }
        
        // 将调用数据保存到同步传输器中
        transport->calldata(transport, entry);
        // 将同步传输器存储到并行调用器中。
        multi->add(multi, transport);
        // 释放请求
        php_yar_request_destroy(request);
    } ZEND_HASH_FOREACH_END();

    // 执行所有请求
    if (!multi->exec(multi, php_yar_concurrent_client_callback)) {
        multi->close(multi);
        return 0;
    }

    // 释放资源
    multi->close(multi);
    return 1;
}

我们看下并行传输器中函数指针对应的函数。

(gdb) p *multi
$10 = {data = 0x7ffff5461050, add = 0x7ffff56eea4e <php_yar_curl_multi_add_handle>,
  exec = 0x7ffff56ef1e4 <php_yar_curl_multi_exec>, close = 0x7ffff56ef6af <php_yar_curl_multi_close>}

可以看到 add、exec、close 分别对应 php_yar_curl_multi_add_handle、php_yar_curl_multi_exec、php_yar_curl_multi_close 等函数，分别在这些函数上打断点，然后继续运行程序。

(gdb) b php_yar_curl_multi_add_handle
Breakpoint 3 at 0x7ffff56eea4e: file /home/vagrant/code/her-cat/yar/transports/curl.c, line 604.
(gdb) b php_yar_curl_multi_exec
Breakpoint 4 at 0x7ffff56ef1e4: file /home/vagrant/code/her-cat/yar/transports/curl.c, line 748.
(gdb) b php_yar_curl_multi_close
Breakpoint 5 at 0x7ffff56ef6af: file /home/vagrant/code/her-cat/yar/transports/curl.c, line 951.
(gdb) c
Continuing.

Breakpoint 3, php_yar_curl_multi_add_handle (self=0x7ffff5402428, handle=0x7ffff548e060)
    at /home/vagrant/code/her-cat/yar/transports/curl.c:604
warning: Source file is more recent than executable.
604    int php_yar_curl_multi_add_handle(yar_transport_multi_interface_t *self, yar_transport_interface_t *handle) /* {{{ */ {
(gdb)

php_yar_curl_multi_add_handle

php_yar_curl_multi_add_handle 函数的作用：将同步传输器实例以头插法保存到 chs 单链表中。

// source：transports/curl.c

int php_yar_curl_multi_add_handle(yar_transport_multi_interface_t *self, yar_transport_interface_t *handle) {
    yar_curl_multi_data_t *multi = (yar_curl_multi_data_t *)self->data;
    yar_curl_data_t *data = (yar_curl_data_t *)handle->data;

    // 预处理，将传输数据保存到 curl 中
    php_yar_curl_prepare(handle);

    // 将同步传输器的 curl 实例添加到 curl 批处理实例中
    curl_multi_add_handle(multi->cm, data->cp);

    // 头插法保存
    if (multi->chs) {
        data->next = multi->chs;
        multi->chs = handle;
    } else {
        multi->chs = handle;
    }

    return 1;
}

php_yar_curl_multi_exec

php_yar_curl_multi_exec 函数的作用：通过 epoll 或 select 多路复用机制监控文件描述符的状态，并配合 curl_multi_* 系列函数对请求进行处理。

以下是主要逻辑：

  • 从 curl 批处理实例中取出所有请求的文件描述符。
  • 调用 select 函数监听文件描述符的状态，阻塞当前进程。
  • 进程从休眠状态恢复后，调用 curl_multi_perform 处理响应数据。
  • 调用 php_yar_curl_multi_parse_response 函数解析响应数据。
// source：transports/curl.c

int php_yar_curl_multi_exec(yar_transport_multi_interface_t *self, yar_concurrent_client_callback *f) /* {{{ */ {
    int running_count, rest_count;
    yar_curl_multi_data_t *multi = (yar_curl_multi_data_t *)self->data;

    // 尝试让 libcurl 处理数据，并获取当前正在运行中的数量
    while (CURLM_CALL_MULTI_PERFORM == curl_multi_perform(multi->cm, &running_count));

    // 第一次调用回调函数，让调用方执行自己的逻辑。
    if (!f(NULL, YAR_ERR_OKEY, NULL)) {
        goto bailout;
    }

    if (running_count) {
        rest_count = running_count;
        do {
            int max_fd, return_code;
            struct timeval tv;
            fd_set readfds;
            fd_set writefds;
            fd_set exceptfds;

            FD_ZERO(&readfds);
            FD_ZERO(&writefds);
            FD_ZERO(&exceptfds);
            
            // 从 curl 批处理实例中取出所有请求的文件描述符
            curl_multi_fdset(multi->cm, &readfds, &writefds, &exceptfds, &max_fd);
            if (max_fd == -1) {
                // max_fd 为 -1 说明 libcurl 正在处理一些不能使用套接字监控的事情，
                // 所以需要等待一会再调用 curl_multi_perform
                long timeout;
                curl_multi_timeout(multi->cm, &timeout);
                if (timeout < 0) {
                    timeout = 50;
                }
                if (timeout) {
                    tv.tv_sec = timeout / 1000;
                    tv.tv_usec = (timeout % 1000) * 1000;
                    select(1, &readfds, &writefds, &exceptfds, &tv);
                }
                // 让 libcurl 处理数据
                while (CURLM_CALL_MULTI_PERFORM == curl_multi_perform(multi->cm, &running_count));
                goto process;
            }

            // 计算 select 超时时间
            tv.tv_sec = (zend_ulong)(YAR_G(timeout) / 1000);
            tv.tv_usec = (zend_ulong)((YAR_G(timeout) % 1000)? (YAR_G(timeout) % 1000) * 1000 : 0);

            // 等待请求返回数据
            return_code = select(max_fd + 1, &readfds, &writefds, &exceptfds, &tv);
            if (return_code > 0) {
                // 说明某些文件描述符可读/可写，让 libcurl 进行处理
                while (CURLM_CALL_MULTI_PERFORM == curl_multi_perform(multi->cm, &running_count));
            } else if (-1 == return_code) {
                // 发生异常
                php_error_docref(NULL, E_WARNING, "select error '%s'", strerror(errno));
                goto onerror;
            } else {
                // 等待超时
                php_error_docref(NULL, E_WARNING, "select timeout %ldms reached", YAR_G(timeout));
                goto onerror;
            }
process:
            if (rest_count > running_count) {
                // 解析响应的数据
                int ret = php_yar_curl_multi_parse_response(multi, f);
                if (ret == -1) {
                    goto bailout;
                } else if (ret == 0) {
                    goto onerror;
                }
                rest_count = running_count;
            }
        } while (running_count);
    } else {
        // 第一次尝试让 libcurl 处理数据后，
        // 如果运行中的数量为 0 ，说明已经全部处理完了，
        // 直接进行解析
        int ret = php_yar_curl_multi_parse_response(multi, f);
        if (ret == -1) {
            goto bailout;
        } else if (ret == 0) {
            goto onerror;
        }
    }

    return 1;
onerror:
    return 0;
bailout:
    self->close(self);
    zend_bailout();
    return 0;
}

php_yar_curl_multi_parse_response

在 php_yar_curl_multi_parse_response 函数上打断点，然后继续运行程序。

(gdb) b php_yar_curl_multi_parse_response
Breakpoint 6 at 0x7ffff56eeadb: file /home/vagrant/code/her-cat/yar/transports/curl.c, line 622.
(gdb) c
Continuing.

Breakpoint 6, php_yar_curl_multi_parse_response (multi=0x20b666f03b932500, f=0x16fb)
    at /home/vagrant/code/her-cat/yar/transports/curl.c:622
622    static int php_yar_curl_multi_parse_response(yar_curl_multi_data_t *multi, yar_concurrent_client_callback *f) /* {{{ */ {
(gdb)

php_yar_curl_multi_parse_response 函数的主要逻辑：

  • 从 curl 批处理实例中取出所有收到的响应数据。
  • 遍历 multi->chs 找到数据对应的同步传输器。
  • 检查响应数据是否正确。
  • 解析响应数据，得到 Yar 协议中的头部及 payload 部分的内容。
  • 调用 php_yar_concurrent_client_callback 函数，执行对应的回调函数。
// source：transports/curl.c

static int php_yar_curl_multi_parse_response(yar_curl_multi_data_t *multi, yar_concurrent_client_callback *f) {
    int msg_in_sequence;
    CURLMsg *msg;

    do {
        // 从 curl 批处理实例中读取一条消息，并返回剩余消息数量（msg_in_sequence）
        msg = curl_multi_info_read(multi->cm, &msg_in_sequence);
        if (msg && msg->msg == CURLMSG_DONE) {
            // 标记是否找到了对应的同步传输器
            unsigned found = 0;
            yar_transport_interface_t *handle = multi->chs, *q = NULL;

            // 遍历单链表
            while (handle) {
                // curl 实例的指针地址相等，说明找到了
                if (msg->easy_handle == ((yar_curl_data_t*)handle->data)->cp) {
                    // 从单链表中移除
                    if (q) {
                        ((yar_curl_data_t *)q->data)->next = ((yar_curl_data_t*)handle->data)->next;
                    } else {
                        multi->chs = ((yar_curl_data_t*)handle->data)->next;
                    }
                    found = 1;
                    break;
                }
                q = handle;
                handle = ((yar_curl_data_t*)handle->data)->next;
            }

            if (found) {
                long http_code = 200;
                yar_response_t *response;
                yar_curl_data_t *data = (yar_curl_data_t *)handle->data;

                // 创建响应实例
                response = php_yar_response_instance();

                if (msg->data.result == CURLE_OK) {
                    curl_multi_remove_handle(multi->cm, data->cp);
                    
                    // 获取 HTTP 状态码
                    if(curl_easy_getinfo(data->cp, CURLINFO_RESPONSE_CODE, &http_code) == CURLE_OK && http_code != 200) {
                        // 非 200 说明出现异常
                        // 返回异常响应
                        continue;
                    } else {
                        // 状态码为 200 
                        if (data->buf.s) {
                            // ...
                            
                            // 从响应数据中解析出 Yar 协议的头部信息
                            if (!(header = php_yar_protocol_parse(payload))) {
                                php_yar_error(response, YAR_ERR_PROTOCOL, "malformed response header '%.32s'", payload);
                            } else {
                                // 跳过 Yar 协议的头部信息后的内容，就是真正的响应结果
                                payload += sizeof(yar_header_t);
                                payload_len -= sizeof(yar_header_t);
                                
                                // 通过 payload 中的编码方式对 payload 进行解码
                                if (!(retval = php_yar_packager_unpack(payload, payload_len, &msg, &ret))) {
                                    php_yar_response_set_error(response, YAR_ERR_PACKAGER, msg, strlen(msg));
                                } else {
                                    // 将解码后的数据存储到 response 中
                                    php_yar_response_map_retval(response, retval);
                                    DEBUG_C(ZEND_ULONG_FMT": server response content packaged by '%.*s', len '%ld', content '%.32s'", response->id, 7, payload, header->body_len, payload + 8);
                                    zval_ptr_dtor(retval);
                                }
                                if (msg) {
                                    efree(msg);
                                }
                            }
                        } else {
                            // 响应内容为空，设置错误信息
                            php_yar_response_set_error(response, YAR_ERR_EMPTY_RESPONSE, ZEND_STRL("empty response"));
                        }

                        // 调用 php_yar_concurrent_client_callback 函数
                        if (!f(data->calldata, response->status, response)) {
                            handle->close(handle);
                            php_yar_response_destroy(response);
                            return -1;
                        }
                        if (EG(exception)) {
                            handle->close(handle);
                            php_yar_response_destroy(response);
                            return 0;
                        }
                    }
                } else {
                    // 执行请求失败，返回失败原因
                    char *err = (char *)curl_easy_strerror(msg->data.result);
                    php_yar_response_set_error(response, YAR_ERR_TRANSPORT, err, strlen(err));
                    if (!f(data->calldata, YAR_ERR_TRANSPORT, response)) {
                        handle->close(handle);
                        php_yar_response_destroy(response);
                        return -1;
                    }
                    if (EG(exception)) {
                        handle->close(handle);
                        php_yar_response_destroy(response);
                        return 0;
                    }
                }
                handle->close(handle);
                php_yar_response_destroy(response);
            } else {
                php_error_docref(NULL, E_WARNING, "unexpected transport info missed");
            }
        }
    } while (msg_in_sequence);

    return 1;
}

php_yar_concurrent_client_callback

该函数的作用：通过响应状态判断本次远程调用的结果，执行相应的回调函数。

主要逻辑：

  • 通过响应状态获取要执行的 PHP 回调函数。
  • 组装被调用函数的参数。
  • 执行 PHP 回调函数。
// source：yar_client.c

int php_yar_concurrent_client_callback(yar_call_data_t *calldata, int status, yar_response_t *response) /* {{{ */ {
    zval code, retval, retval_ptr;
    zval callinfo, *callback, func_params[3];
    zend_bool bailout = 0;
    unsigned params_count, i;

    if (calldata) {
        // 通过响应状态获取要执行的 PHP 回调函数
        if (status == YAR_ERR_OKEY) {
            if (!Z_ISUNDEF(calldata->callback)) {
                callback = &calldata->callback;
            } else {
                callback = zend_read_static_property(yar_concurrent_client_ce, ZEND_STRL("_callback"), 0);
            }
            params_count = 2;
        } else {
            if (!Z_ISUNDEF(calldata->ecallback)) {
                callback = &calldata->ecallback;
            } else {
                callback = zend_read_static_property(yar_concurrent_client_ce, ZEND_STRL("_error_callback"), 0);
            }
            params_count = 3;
        }

        // 没获取到回调函数就提示错误信息
        if (Z_ISNULL_P(callback)) {
            if (status != YAR_ERR_OKEY) {
                if (!Z_ISUNDEF(response->err)) {
                    php_yar_client_handle_error(0, response);
                } else {
                    php_error_docref(NULL, E_WARNING, "[%d]:unknown Error", status);
                }
            } else if (!Z_ISUNDEF(response->retval)) {
                zend_print_zval(&response->retval, 1);
            }
            return 1;
        }

        if (status == YAR_ERR_OKEY) {
            // 响应状态是成功但是返回值为空，提示错误信息。
            if (Z_ISUNDEF(response->retval)) {
                php_yar_client_trigger_error(0, YAR_ERR_REQUEST, "%s", "server responsed empty response");
                return 1;
            }
            // 复制返回值
            ZVAL_COPY(&retval, &response->retval);
        } else {
            // 复制状态及错误信息
            ZVAL_LONG(&code, status);
            ZVAL_COPY(&retval, &response->err);
        }

        // 初始化调用信息
        array_init(&callinfo);

        add_assoc_long_ex(&callinfo, "sequence", sizeof("sequence") - 1, calldata->sequence);
        add_assoc_str_ex(&callinfo, "uri", sizeof("uri") - 1, zend_string_copy(calldata->uri));
        add_assoc_str_ex(&callinfo, "method", sizeof("method") - 1, zend_string_copy(calldata->method));
    } else {
        // 调用数据为空则获取并行客户端的回调函数
        callback = zend_read_static_property(yar_concurrent_client_ce, ZEND_STRL("_callback"), 0);
        if (Z_ISNULL_P(callback)) {
            return 1;
        }
        params_count = 2;
    }

    if (calldata && (status != YAR_ERR_OKEY)) {
        // 调用失败
        ZVAL_COPY_VALUE(&func_params[0], &code);
        ZVAL_COPY_VALUE(&func_params[1], &retval);
        ZVAL_COPY_VALUE(&func_params[2], &callinfo);
    } else if (calldata) {
        // 调用成功
        ZVAL_COPY_VALUE(&func_params[0], &retval);
        ZVAL_COPY_VALUE(&func_params[1], &callinfo);
    } else {
        // 调用数据为空
        ZVAL_NULL(&func_params[0]);
        ZVAL_NULL(&func_params[1]);
    }

    zend_try {
        // 执行回调函数
        if (call_user_function(EG(function_table), NULL, callback, &retval_ptr, params_count, func_params) != SUCCESS) {
            for (i = 0; i < params_count; i++) {
                zval_ptr_dtor(&func_params[i]);    
            }
            if (calldata) {
                php_error_docref(NULL, E_WARNING, "call to callback failed for request: '%s'", ZSTR_VAL(calldata->method));
            } else {
                php_error_docref(NULL, E_WARNING, "call to initial callback failed");
            }
            return 1;
        }
    } zend_catch {
        bailout = 1;
    } zend_end_try();

    // 释放返回值及参数
    if (!Z_ISUNDEF(retval_ptr)) {
        zval_ptr_dtor(&retval_ptr);
    }

    for (i = 0; i < params_count; i++) {
        zval_ptr_dtor(&func_params[i]);    
    }
    return bailout? 0 : 1;
}

打印 retval 可以看到服务端的返回值：success。

(gdb) p *retval.value.str.val@7
$28 = "success"

总结

本文介绍了实现并行调用相关的数据结构，并通过 GDB 调试代码的方式展示了并行调用运行的过程。

]]> Yar 源码阅读笔记：客户端的同步调用 https://her-cat.com/posts/2022/01/07/yar-internals-client-sync-call/ Fri, 07 Jan 2022 16:13:08 +0800 https://her-cat.com/posts/2022/01/07/yar-internals-client-sync-call/ 主要介绍 Yar 客户端是如何实现远程调用的，进一步了解各个模块在远程调用的过程中都做了些什么。 前言

今天这篇文章，主要介绍 Yar 客户端是如何实现远程调用的，进一步了解各个模块在远程调用的过程中都做了些什么。

客户端介绍

Yar 客户端的远程调用分为同步调用和并行调用，同步调用是指调用多个远程方法时，必须按照调用顺序一个个地执行，上一个调用没有执行完时，后面的调用必须等待前面的执行完毕，这期间啥也不能干，效率比较低。

这时候就有了并行调用，从名字就可以看出来，并行调用支持同时调用多个远程方法。它会先将所有的调用请发送出去，让服务端开始处理这些请求，然后客户开始端监听每个请求的响应结果，当这些请求中有任何一个请求有响应结果时，执行该请求的回调函数处理相应的业务逻辑。

这篇文章主要介绍同步调用的实现，所以在本文中提到 “远程调用” 都是指同步调用。

我们先来看看开篇中客户端同步调用的例子。

// 实例化客户端
$client = new Yar_Client("http://127.0.0.1:3000/server.php");

// 设置超时时间
$client->setOpt(YAR_OPT_CONNECT_TIMEOUT, 1000);

// 调用 login 方法
$result = $client->login("her-cat", "123456");

var_dump($result);

通过上面的例子可以知道，客户端中有三个主要方法：

  • 构造函数：用于传入服务端的地址以及可选配置。
  • setOpt：设置配置项，比如连接超时时间等。
  • 远程方法：调用服务端定义好的方法，这里是 login。

当然客户端类还有一些的方法以及属性，可以在定义客户端类的地方找到：

// source：yar_client.c

// 客户端方法列表
zend_function_entry yar_client_methods[] = {
    PHP_ME(yar_client, __construct, arginfo_client___construct, ZEND_ACC_PUBLIC|ZEND_ACC_CTOR|ZEND_ACC_FINAL)
    PHP_ME(yar_client, call, arginfo_client___call, ZEND_ACC_PUBLIC)
    PHP_ME(yar_client, __call, arginfo_client___call, ZEND_ACC_PUBLIC)
    PHP_ME(yar_client, getOpt, arginfo_client_getopt, ZEND_ACC_PUBLIC)
    PHP_ME(yar_client, setOpt, arginfo_client_setopt, ZEND_ACC_PUBLIC)
    PHP_FE_END
};

YAR_STARTUP_FUNCTION(client) /* {{{ */ {
    zend_class_entry ce;

    INIT_CLASS_ENTRY(ce, "Yar_Client", yar_client_methods);
    yar_client_ce = zend_register_internal_class(&ce);

    // 声明客户端的属性
    zend_declare_property_long(yar_client_ce, ZEND_STRL("_protocol"), YAR_CLIENT_PROTOCOL_HTTP, ZEND_ACC_PROTECTED);
    zend_declare_property_null(yar_client_ce, ZEND_STRL("_uri"), ZEND_ACC_PROTECTED);
    zend_declare_property_null(yar_client_ce, ZEND_STRL("_options"),  ZEND_ACC_PROTECTED);
    zend_declare_property_null(yar_client_ce, ZEND_STRL("_running"),  ZEND_ACC_PROTECTED);

    // 注册协议常量
    REGISTER_LONG_CONSTANT("YAR_CLIENT_PROTOCOL_HTTP", YAR_CLIENT_PROTOCOL_HTTP, CONST_PERSISTENT | CONST_CS);
    REGISTER_LONG_CONSTANT("YAR_CLIENT_PROTOCOL_TCP", YAR_CLIENT_PROTOCOL_TCP, CONST_PERSISTENT | CONST_CS);
    REGISTER_LONG_CONSTANT("YAR_CLIENT_PROTOCOL_UNIX", YAR_CLIENT_PROTOCOL_UNIX, CONST_PERSISTENT | CONST_CS);

    return SUCCESS;
}

下面我们重点来看看客户端远程调用的实现，客户端中的其它方法比较简单，这里就不赘述了。

同步调用

熟悉 PHP 的应该都知道，当我们调用对象中未定义或不可访问的方法时，PHP 会尝试调用魔术方法 __call，当 __call 方法也未定义时，将会抛出调用未定义方法的异常。

class A 
{
    public function __call($name, $arguments)
    {
        echo "调用 A 的 '{$name}' 方法，参数是：" . implode('，', $arguments) . "\n";
    }
}

$a = new A();
$a->login("her-cat", "123456");

// 输出：调用 A 的 login 方法，参数是：her-cat，123456

Yar 就是通过 __call 实现了远程调用。

虽然在代码中看起来调用的是客户端的方法，但实际上是通过 __call 魔术方法，将调用的请求转发到服务端上，让服务端执行对应的方法，最后将执行的结果返回，完成了整个远程调用。

下面是客户端执行同步调用时的调用栈。

Client::__call

在上面的客户端介绍中的客户端方法列表中，可以看到 Yar 实现了 __call 和 call 方法。

// source：yar_client.c

/* {{{ proto Yar_Client::call($method, $parameters = NULL) */
PHP_METHOD(yar_client, call) {
    PHP_MN(yar_client___call)(INTERNAL_FUNCTION_PARAM_PASSTHRU);
}
/* }}} */

call 函数实际上是 __call 函数的一层包装，可以理解为别名方法。

// source：yar_client.c

PHP_METHOD(yar_client, __call) {
    zval *params, *protocol, rv;
    zval *this_ptr = getThis();

    // 解析参数，被调用的方法名称和参数数组
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "Sa", &method, &params) == FAILURE) {
        return;
    }

    // 读取使用的协议
    protocol = zend_read_property(yar_client_ce, this_ptr, ZEND_STRL("_protocol"), 0, &rv);

    // 根据协议调用对应的方法
    switch (Z_LVAL_P(protocol)) {
        case YAR_CLIENT_PROTOCOL_TCP:
        case YAR_CLIENT_PROTOCOL_UNIX:
        case YAR_CLIENT_PROTOCOL_HTTP:
            if ((php_yar_client_handle(Z_LVAL_P(protocol), getThis(), method, params, return_value))) {
                return;
            }
            break;
        default:
            php_error_docref(NULL, E_WARNING, "unsupported protocol %ld", Z_LVAL_P(protocol));
            break;
    }

    RETURN_FALSE;
}

__call 函数的内容比较简单，先解析参数，得到被调用的方法名称和参数数组，然后从客户端对象中读取协议，然后根据协议调用对应的函数，当遇到不支持的协议时，提示错误信息并返回 false。

php_yar_client_handle

php_yar_client_handle 函数包含了整个调用的过程，它就是客户端实现远程调用的核心所在。

// source：yar_client.c

static int php_yar_client_handle(int protocol, zval *client, zend_string *method, zval *params, zval *retval) {
    char *msg;
    zval *uri, *options;
    zval rv;
    const yar_transport_t *factory;
    yar_transport_interface_t *transport;
    yar_request_t *request;
    yar_response_t *response;
    int flags = 0;
    zval *zobj = client;

    // 读取服务端的地址
    uri = zend_read_property(yar_client_ce, zobj, ZEND_STRL("_uri"), 0, &rv);

    // 通过协议获取对应的传输方式
    if (protocol == YAR_CLIENT_PROTOCOL_HTTP) {
        factory = php_yar_transport_get(ZEND_STRL("curl"));
    } else if (protocol == YAR_CLIENT_PROTOCOL_TCP || protocol == YAR_CLIENT_PROTOCOL_UNIX) {
        factory = php_yar_transport_get(ZEND_STRL("sock"));
    } else {
        return 0;
    }

    // 初始化传输方式
    transport = factory->init();

    options = zend_read_property(yar_client_ce, zobj, ZEND_STRL("_options"), 1, &rv);

    if (IS_ARRAY != Z_TYPE_P(options)) {
        options = NULL;
    }
    
    // 根据被调用的方法名称、参数等信息组装请求数据
    if (UNEXPECTED(!(request = php_yar_request_instance(method, params, options)))) {
        transport->close(transport);
        factory->destroy(transport);
        return 0;
    }

    if (options) {
        zval *flag = php_yar_client_get_opt(options, YAR_OPT_PERSISTENT);
        if (flag && (Z_TYPE_P(flag) == IS_TRUE || (Z_TYPE_P(flag) == IS_LONG && Z_LVAL_P(flag)))) {
            flags |= YAR_PROTOCOL_PERSISTENT;
        }
    }


    msg = (char*)options;
    // 打开/创建一个连接
    if (UNEXPECTED(!transport->open(transport, Z_STR_P(uri), flags, &msg))) {
        php_yar_client_trigger_error(1, YAR_ERR_TRANSPORT, msg);
        php_yar_request_destroy(request);
        ZEND_ASSERT(msg != (char*)options);
        efree(msg);
        transport->close(transport);
        factory->destroy(transport);
        return 0;
    }

    // 对请求数据进行编码、组装等操作，并将处理后的数据保存到连接中
    if (UNEXPECTED(!transport->send(transport, request, &msg))) {
        php_yar_client_trigger_error(1, YAR_ERR_TRANSPORT, msg);
        php_yar_request_destroy(request);
        efree(msg);
        transport->close(transport);
        factory->destroy(transport);
        return 0;
    }

    // 执行请求
    response = transport->exec(transport, request);

    if (UNEXPECTED(response->status != YAR_ERR_OKEY)) {
        // 调用失败则返回异常响应
        php_yar_client_handle_error(1, response);
        php_yar_request_destroy(request);
        php_yar_response_destroy(response);
        transport->close(transport);
        factory->destroy(transport);
        return 0;
    } else {
        if (response->out && ZSTR_LEN(response->out)) {
            PHPWRITE(ZSTR_VAL(response->out), ZSTR_LEN(response->out));
        }
        // 调用成功则将响应值拷贝到返回值中。
        ZVAL_COPY(retval, &response->retval);
        php_yar_request_destroy(request);
        php_yar_response_destroy(response);
        transport->close(transport);
        factory->destroy(transport);
        return 1;
    }
}

php_yar_client_handle 函数的主要逻辑都写上注释了，transport 调用的那些函数，就是上一篇文章中的那些 curl 函数，我们可以使用 gdb 打印 transport 的值进行验证。

(gdb) p *transport
$8 = {data = 0x7ffff5481000, open = 0x7ffff56ecd4b <php_yar_curl_open>, send = 0x7ffff56ee293 <php_yar_curl_send>,
  exec = 0x7ffff56eddc0 <php_yar_curl_exec>, setopt = 0x7ffff56ee78f <php_yar_curl_setopt>,
  calldata = 0x7ffff56ee761 <php_yar_curl_set_calldata>, close = 0x7ffff56edaa1 <php_yar_curl_close>}

总结

下一篇文章将会介绍客户端并行调用的实现，并行调用也是 Yar 的亮点之一，其实现相对同步调用来说，会稍微复杂那么一丢丢。

]]> Yar 源码阅读笔记：数据传输模块 https://her-cat.com/posts/2022/01/06/yar-internals-transport/ Thu, 06 Jan 2022 19:08:06 +0800 https://her-cat.com/posts/2022/01/06/yar-internals-transport/ 主要介绍 Yar 编码模块的结构体定义，以及 HTTP 传输方式的实现。 前言

在前面几篇文章中，更多的是在研究 Yar 传输的内容，比如协议的格式是什么样的、如何对数据进行编码等等。

今天这篇文章，主要介绍 Yar 编码模块的结构体定义，以及 HTTP 传输方式的实现，更深入的了解 Yar 的协议数据是如何被发送出去的。

传输模块结构体

在 RPC 通信协议 中有提到过，Yar 支持 HTTP 和 TCP 两种数据传输方式，前者使用 curl，后者使用 socket。

yar_transport_t

我们可以将 yar_transport_t 结构体看作是同步传输器的工厂，用于创建和释放同步传输器的实例。

// source：yar_transport.h

// 同步传输器的工厂
typedef struct _yar_transport {
    const char *name;
    struct _yar_transport_interface * (*init)();
    void (*destroy)(yar_transport_interface_t *self);
    yar_transport_multi_t *multi;
} yar_transport_t;

结构体字段说明：

  • name：传输方式的名称，比如 “curl”。
  • init：函数指针，创建同步传输器实例并初始化相关配置，函数的返回值是结构体 _yar_transport_interface 的指针。
  • destroy：函数指针，释放某个同步传输器的资源，函数的参数是结构体 _yar_transport_interface 的指针。
  • multi：用于实现并行调用的结构体指针，这部分会在并行调用进行详解。

yar_transport_interface_t

在 yar_transport_t 结构体中，只定义了 init 和 destroy 这两个函数指针，用于对同步传输器的创建和释放。而真正用于传输时使用的相关函数，则放在了 yar_transport_interface_t 结构体中。

// source：yar_transport.h

// 同步传输器
typedef struct _yar_transport_interface {
    void *data;
    int  (*open)(struct _yar_transport_interface *self, zend_string *address, long options, char **msg);
    int  (*send)(struct _yar_transport_interface *self, struct _yar_request *request, char **msg);
    struct _yar_response * (*exec)(struct _yar_transport_interface *self, struct _yar_request *request);
    int  (*setopt)(struct _yar_transport_interface *self, long type, void *value, void *addition);
    int  (*calldata)(struct _yar_transport_interface *self, yar_call_data_t *calldata);
    void (*close)(struct _yar_transport_interface *self);
} yar_transport_interface_t;

结构体说明：

  • data：存储传输相关的数据指针，比如 curl 是 yar_curl_data_t 结构体，socket 是 yar_socket_data_t 结构体。
  • open：函数指针，打开/创建一个连接，并初始化相关默认值。
  • send：函数指针，对请求数据进行编码、组装等操作，并将处理后的数据保存到连接中。
  • exec：函数指针，执行请求，将连接中的数据发送出去。
  • setopt：函数指针，设置连接相关的选项，比如编码方式、超时时间。
  • calldata：函数指针，设置回调时的数据，在并行调用时才会用到。
  • close：函数指针：关闭连接并释放相关的资源。

HTTP 传输方式

Yar 支持的传输方式都放在了 transports 目录下，因为 HTTP 是 Yar 默认的数据传输方式，并且服务端也只实现了 HTTP 这种方式，所以我们这里用 HTTP 进行举例。

用 c 语言实现 HTTP 请求的类库有很多，Yar 使用的是 curl，所以在 transports 目录下的文件命名是 curl.c。

yar_transport_t

根据前面传输模块的介绍，首先需要实现 yar_transport_t 结构体。

// source：transports/curl.c

const yar_transport_t yar_transport_curl = {
    "curl",
    php_yar_curl_init,
    php_yar_curl_destroy,
    &yar_transport_curl_multi
};

curl 是传输方式的名称，php_yar_curl_init 和 php_yar_curl_destroy 是 init 和 destroy 这两个函数指针的实现，yar_transport_curl_multi 用来实现并行调用。

先来看看 php_yar_curl_init 函数。

// source：transports/curl.c

yar_transport_interface_t *php_yar_curl_init() {
    yar_curl_data_t *data;
    yar_transport_interface_t *self;

    // 分配 yar_transport_interface_t 结构体及数据的内存
    self = ecalloc(1, sizeof(yar_transport_interface_t));
    self->data = data = ecalloc(1, sizeof(yar_curl_data_t));

    // 设置 Yar 的 HTTP 头部信息
    /* snprintf(content_type, sizeof(content_type), "Content-Type: %s", YAR_G(content_type)); */
    data->headers = curl_slist_append(data->headers, "User-Agent: PHP Yar RPC-" PHP_YAR_VERSION);
    data->headers = curl_slist_append(data->headers, "Expect:");

    // 设置各个函数指针对应的函数实现
    self->open       = php_yar_curl_open;
    self->send       = php_yar_curl_send;
    self->exec       = php_yar_curl_exec;
    self->setopt     = php_yar_curl_setopt;
    self->calldata   = php_yar_curl_set_calldata;
    self->close      = php_yar_curl_close;

    // 分配响应数据及请求数据的内存，默认为 1M
    smart_str_alloc((&data->buf), YAR_PACKAGER_BUFFER_SIZE /* 1M */, 0);
    smart_str_alloc((&data->postfield), YAR_PACKAGER_BUFFER_SIZE /* 1M */, 0);

    // 返回 yar_transport_interface_t 结构体的指针
    return  self;
}

由于没有资源需要在 destroy 的时候进行释放，所以 php_yar_curl_destroy 是一个空函数。

// source：transports/curl.c

void php_yar_curl_destroy(yar_transport_interface_t *self) {
}

yar_transport_interface_t

接下来看看 curl 中 yar_transport_interface_t 相关的实现。

首先是 php_yar_curl_open 函数，以下是该函数的主要逻辑：

  • 如果开启了连接持久化，则尝试从持久化的连接池中找到未使用的连接。
  • 没有找到符合条件的连接或者未开启连接持久化，则直接创建一个新的 curl 实例。
  • 解析请求地址，并将请求信息及 curl 实例保存到 data 中，方便后续在其它函数中使用。
  • 如果开启了连接持久化，则设置 keep-alive 及 keep-alive 有效时间的头部信息。
  • 设置自定义的头部信息及域名。
  • 设置 curl 收到响应时的回调函数及其它 curl 选项。
  • 设置 curl 请求地址。

打开连接之后，调用 php_yar_curl_send 函数对请求数据进行编码、组装等操作。

// source：transports/curl.c

int php_yar_curl_send(yar_transport_interface_t* self, yar_request_t *request, char **msg) {
    yar_header_t header = {0};
    yar_curl_data_t *data = (yar_curl_data_t *)self->data;
    zend_string *payload;

    // 对请求数据进行编码
    if (!(payload = php_yar_request_pack(request, msg))) {
        return 0;
    }

    // 通过编码后的数据初始化 header 结构体
    php_yar_protocol_render(&header, request->id, data->host->user, data->host->pass, ZSTR_LEN(payload), 0);

    // 将 header 及 payload 按照顺序追加到请求数据的 buf 中
    smart_str_appendl(&data->postfield, (char *)&header, sizeof(yar_header_t));
    smart_str_appendl(&data->postfield, ZSTR_VAL(payload), ZSTR_LEN(payload));
    zend_string_release(payload);

    return 1;
}

数据准备就绪后，就可以调用 php_yar_curl_exec 函数执行请求，将数据发送出去并解析响应结果。

// source：transports/curl.c

yar_response_t *php_yar_curl_exec(yar_transport_interface_t* self, yar_request_t *request) {
    // ...

    // 设置请求数据及大小
    curl_easy_setopt(data->cp, CURLOPT_POSTFIELDS, ZSTR_VAL(data->postfield.s));
    curl_easy_setopt(data->cp, CURLOPT_POSTFIELDSIZE, ZSTR_LEN(data->postfield.s));

    // 设置超时时间等选项
    if (IS_ARRAY == Z_TYPE(request->options)) {
        zval *pzval;
        if ((pzval = zend_hash_index_find(Z_ARRVAL(request->options), YAR_OPT_TIMEOUT))) {
            convert_to_long_ex(pzval);
            self->setopt(self, YAR_OPT_TIMEOUT, (long *)&Z_LVAL_P(pzval), NULL);
        }
        if ((pzval = zend_hash_index_find(Z_ARRVAL(request->options), YAR_OPT_CONNECT_TIMEOUT))) {
            convert_to_long_ex(pzval);
            self->setopt(self, YAR_OPT_CONNECT_TIMEOUT, (long *)&Z_LVAL_P(pzval), NULL);
        }
        if ((pzval = zend_hash_index_find(Z_ARRVAL(request->options), YAR_OPT_PROXY))) {
            convert_to_string_ex(pzval);
            self->setopt(self, YAR_OPT_PROXY, (char *)&Z_STRVAL_P(pzval), NULL);
        }
    }

    response = php_yar_response_instance();

    // 执行请求
    ret = curl_easy_perform(data->cp);
    if (ret != CURLE_OK) {
        // 请求失败则将失败信息保存到 response 中并返回
        len = spprintf(&msg, 0, "curl exec failed '%s'", curl_easy_strerror(ret));
        php_yar_response_set_error(response, YAR_ERR_TRANSPORT, msg, len);
        efree(msg);
        return response;
    } else {
        long http_code;
        // 检查响应状态码是否等于 200
        if(curl_easy_getinfo(data->cp, CURLINFO_RESPONSE_CODE, &http_code) == CURLE_OK 
                && http_code != 200) {
            len = spprintf(&msg, 0, "server responsed non-200 code '%ld'", http_code);
            php_yar_response_set_error(response, YAR_ERR_TRANSPORT, msg, len);
            efree(msg);
            return response;
        }
    }

    if (data->buf.s) {
        // ...

        // 从响应内容中解析出 Yar 协议的头部信息
        if (!(header = php_yar_protocol_parse(payload))) {
            php_yar_error(response, YAR_ERR_PROTOCOL, "malformed response header '%.32s'", payload);
            return response;
        }

        // 跳过 Yar 协议的头部信息后的内容，就是真正的响应结果
        payload += sizeof(yar_header_t);
        payload_len -= sizeof(yar_header_t);

        // 通过 payload 中的编码方式对 payload 进行解码
        if (!(retval = php_yar_packager_unpack(payload, payload_len, &msg, &ret))) {
            php_yar_response_set_error(response, YAR_ERR_PACKAGER, msg, strlen(msg));
            efree(msg);
            return response;
        }

        // 将解码后的数据存储到 response 中
        php_yar_response_map_retval(response, retval);

        zval_ptr_dtor(retval);
    } else {
        // 响应内容为空，设置错误信息
        php_yar_response_set_error(response, YAR_ERR_EMPTY_RESPONSE, ZEND_STRL("empty response"));
    }    

    return response;
}

得到响应结果后，调用 php_yar_curl_close 关闭连接。

// source：transports/curl.c

void php_yar_curl_close(yar_transport_interface_t* self) {
    yar_curl_data_t *data = (yar_curl_data_t *)self->data;

    if (!data) {
        return;
    }

    if (data->cp) {
        if (!data->persistent) {
            // 没有开启连接持久化时，清理 curl 连接
            curl_easy_cleanup(data->cp);
        } else {
            // 否则，设置连接为未使用状态
            data->plink->in_use = 0;
        }
    }

    // 释放 data 中的相关资源
    if (data->host) {
        php_url_free(data->host);
    }

    smart_str_free(&data->buf);
    smart_str_free(&data->postfield);
    curl_slist_free_all(data->headers);

    efree(data);
    efree(self);

    return;
}

总结

这次没有像上一篇文章那样，将传输模块的生命周期各个阶段都写出来，这是因为传输模块在 PHP 生命周期中的几个阶段做的事情跟编码模块差不多，所以就省略掉了。

通过本文可以看出来，Yar 中的 HTTP 传输方式，实际上是对 curl 的一层封装，我写了一个 curl 的小示例，供大家参考。

#include <stdio.h>
#include <curl/curl.h>
#include <curl/easy.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>

#define DEFAULT_BUF_SIZE 1024

typedef struct curl_data_s {
    CURL *cp;
    char *buf;
    uint32_t len;
    uint32_t alloc;
} curl_data_t;

size_t curl_buf_writer(char *ptr, size_t size, size_t nmemb, void *ctx) {
    curl_data_t *data = (curl_data_t *) ctx;
    size_t len = size * nmemb;
    size_t remain = data->alloc - data->len;

    if (len > remain) {
        data->alloc += (len - remain) + DEFAULT_BUF_SIZE;
        data->buf = realloc(data->buf, data->alloc);
        printf("writer, realloc size: %lu\n", (len - remain) + DEFAULT_BUF_SIZE);
    }

    printf("write, len: %zu\n", len);

    memcpy(data->buf + data->len, ptr, len);
    data->len += len;

    return len;
}

int main() {
    curl_data_t data;
    char *address = "https://her-cat.com";
    CURL *cp = curl_easy_init();

    data.cp = cp;
    data.buf = malloc(DEFAULT_BUF_SIZE);
    data.len = 0;
    data.alloc = DEFAULT_BUF_SIZE;

    curl_easy_setopt(cp, CURLOPT_POST, 0);
    curl_easy_setopt(cp, CURLOPT_URL, address);
    curl_easy_setopt(cp, CURLOPT_SSL_VERIFYHOST, 0);
    curl_easy_setopt(cp, CURLOPT_SSL_VERIFYPEER, 0);
    curl_easy_setopt(cp, CURLOPT_WRITEDATA, &data);
    curl_easy_setopt(cp, CURLOPT_WRITEFUNCTION, curl_buf_writer);

    CURLcode ret = curl_easy_perform(cp);
    if (ret != CURLE_OK) {
        printf("curl perform failed, reason: %s\n", curl_easy_strerror(ret));
        return 0;
    }

    long http_code;
    curl_easy_getinfo(cp, CURLINFO_RESPONSE_CODE, &http_code);
    curl_easy_cleanup(cp);
    curl_global_cleanup();

    printf("http code: %ld\n", http_code);
    printf("buf len: %u\n", data.len);
    printf("buf alloc: %u\n", data.alloc);
    printf("response: \n%s\n", data.buf);

    return 0;
}
]]> Yar 源码阅读笔记：消息编码模块 https://her-cat.com/posts/2021/12/23/yar-internals-packager/ Thu, 23 Dec 2021 16:08:05 +0800 https://her-cat.com/posts/2021/12/23/yar-internals-packager/ 今天我们来了解一下，Yar 中的消息编码模块是怎样实现的。 前言

在 上一篇文章 中，我们知道了 Yar 通信协议的格式及作用，还提到了在 Yar 客户端发送请求前和收到响应后，需要先对数据进行编码与解码才能继续进一步操作。

今天我们来了解一下，Yar 中的消息编码模块是怎样实现的。

什么是编码/解码

在介绍 Yar 编码模块之前，我们先来了解一下，什么是编码与解码？

编码（encode）和解码（decode）也有人叫作序列化（serialization）和反序列化（deserialization），其实都是一个意思。

为了统一描述，在后文中都称为编码和解码。

编码是指将数据结构或对象转换成可以存储或传输的数据格式（字节流）。

解码是编码的反向操作，将字节流转换为数据数据结构或对象。

举个例子，假如要将 Person 对象写入到文件中，然后再从文件中还原该对象，应该怎么处理？

class Person 
{
    public $name;
    
    public $age;
}

$person = new Person();
$person->name = 'her-cat';
$person->age = 18;

PHP 提供了两个函数： serialize（编码）和 unserialize（解码）。

serialize 函数可以将除了 resource 类型以外的数据编码为字符串（字节流）。

unserialize 函数可以将编码后的字符串转换为 PHP 的值。

$encoded = file_get_contents('person.txt');
var_dump($encoded);

$decodedPerson = unserialize($encoded);

var_dump($decodedPerson);
var_dump($decodedPerson->name);
var_dump($decodedPerson->age);

string(57) "O:6:"Person":2:{s:4:"name";s:7:"her-cat";s:3:"age";i:18;}"
object(Person)#2 (2) {
  ["name"]=>
  string(7) "her-cat"
  ["age"]=>
  int(18)
}
string(7) "her-cat"
int(18)

为什么需要编码/解码

目的就是为了在不同的编程语言或不同的载体之间交换数据。

上面将对象写入到文件中就是不同载体之间交换数据的例子，这里再举一个不同语言之间的例子。

就拿 PHP 和 JavaScript 来说，我们用 PHP 写了一个 HTTP 接口给 JavaScript 调用，然后 JavaScript 解析 PHP 响应的内容。

PHP 和 JavaScript 是两种不同的编程语言（废话），两者各种数据结构的实现是不一样的，在内存上的组织方式也不一样，所以它们不能直接使用内存中的数据进行数据交换。

就好比两个人在交流，一个人讲蒙古语，另一个人讲粤语，最后两人都不知道对方讲的啥玩意。

所以，我们需要一个中间人帮忙翻译，或者使用两个人都会的一种语言进行交流，比如普通话。

将 “普通话” 代入到上面的例子中，实际上就是引用一种通用的数据编码格式，让 PHP 与 JavaScript 能够进行“交流”。

假设我们使用 JSON，PHP 将数据发送到前端之前，先调用 json_encode 将数据转换成 JSON 字符串（这个过程就是编码）， 前端页面收到 PHP 返回的 JSON 字符串后，将其解析成前端的 JavaScript 的数组/对象（这个过程就是解码）。

Yar 编码模块简介

Yar 提供了三种编码方式：分别是 PHP、JSON、Msgpack。

PHP 是 PHP 内置的一种对数据结构/对象编码的方式，实际上就是使用 serialize 和 unserialize 这对函数，可以参考上面的例子。

JSON 是目前比较通用且流行的一种数据编码格式，由于其简单、易读的特点，所以被广泛地用于 API 接口、JSON-RPC、数据存储等地方。

但是，JSON 也不是一点儿缺点都没有的，JSON 为了保证其可读性，需要多使用一些内存来保存相关信息，所以在数据传输的过程中，占用的内存就会比 Msgpack 这类编码格式要大一些。

Msgpack 一种高效的二进制编码格式，有点儿类似于 JSON，但是比 JSON 占用内存更小、效率更高。

前两种方式在 Yar 中已经内置支持了（直接调用相关的 PHP 函数），Msgpack 则需要自己手动安装扩展，并在编译时指定。

编码模块结构体

Yar 定义了编码模块结构体：yar_packager_t。

// source：yar_packager.h

typedef struct _yar_packager {
    const char *name;
    int  (*pack) (const struct _yar_packager *self, zval *pzval, smart_str *buf, char **msg);
    zval * (*unpack) (const struct _yar_packager *self, char *content, size_t len, char **msg, zval *ret);
} yar_packager_t;

结构体中字段说明：

  • name：编码方式的名称，比如 PHP、JSON、Msgpack。
  • pack：函数指针，对数据进行编码操作。
  • unpack：函数指针，对数据进行解码操作。

yar_packager_t 结构体有点类似于 OOP 中的抽象类，为不同的编码方式提供了统一的接口，从而实现了多态。

如果我们想要扩展一种编码方式，只需要设置编码方式名称并实现 pack 和 unpack 函数即可。

JSON 编码方式

Yar 支持的编码方式都在 packagers 目录下，这里我们用 JSON 方式进行举例。

在 packagers/json.c 文件中定义了一个类型为 yar_packager_t 的常量：yar_packager_json。

const yar_packager_t yar_packager_json = {
    "JSON",
    php_yar_packager_json_pack,
    php_yar_packager_json_unpack
};

首先是编码方式名称 JSON，然后是编码和解码对应的函数，这两个函数其实是对 json_encode 和 json_decode 函数的一层封装。

int php_yar_packager_json_pack(const yar_packager_t *self, zval *pzval, smart_str *buf, char **msg) {
    php_json_encode(buf, pzval, 0);
    return 1;
}

zval * php_yar_packager_json_unpack(const yar_packager_t *self, char *content, size_t len, char **msg, zval *ret) {
    php_json_decode(ret, content, len, 1, 512);
    return ret;
}

其它两种编码方式的实现跟 JSON 差不多，这里就不赘述了。

编码模块的生命周期

Yar 作为 PHP 的扩展，其编码模块的生命周期肯定也是在 PHP 生命周期中的，这里我画了一张图，方便大家能够更直观的了解 Yar 编码模块的生命周期。

接下来看看编码模块在每个阶段中都做了些什么。

启动编码模块

在 PHP 模块初始化阶段，Yar 会先注册一些 Yar 相关的 PHP 常量，比如版本号、客户端相关的选项。紧接着开始初始化模块，除了编码模块以外，还会初始化传输、客户端、服务端及异常等模块。

// source：yar.c

PHP_MINIT_FUNCTION(yar)
{
    // 注册 PHP 常量
    REGISTER_INI_ENTRIES();
    REGISTER_STRINGL_CONSTANT("YAR_VERSION", PHP_YAR_VERSION, sizeof(PHP_YAR_VERSION)-1, CONST_CS|CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("YAR_OPT_PACKAGER", YAR_OPT_PACKAGER, CONST_CS|CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("YAR_OPT_PERSISTENT", YAR_OPT_PERSISTENT, CONST_CS|CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("YAR_OPT_TIMEOUT", YAR_OPT_TIMEOUT, CONST_CS|CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("YAR_OPT_CONNECT_TIMEOUT", YAR_OPT_CONNECT_TIMEOUT, CONST_CS|CONST_PERSISTENT);

    REGISTER_LONG_CONSTANT("YAR_OPT_HEADER", YAR_OPT_HEADER, CONST_CS|CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("YAR_OPT_RESOLVE", YAR_OPT_RESOLVE, CONST_CS|CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("YAR_OPT_PROXY", YAR_OPT_PROXY, CONST_CS|CONST_PERSISTENT);

    // 初始化模块
    YAR_STARTUP(service);
    YAR_STARTUP(client);
    YAR_STARTUP(packager);
    YAR_STARTUP(transport);
    YAR_STARTUP(exception);

    return SUCCESS;
}

今天我们主要研究编码模块，其它几个模块放到后面的文章中。

YAR_STARTUP 是一个宏，定义如下：

#define YAR_STARTUP(module)    ZEND_MODULE_STARTUP_N(yar_##module)(INIT_FUNC_ARGS_PASSTHRU)

/* Name macros */
#define ZEND_MODULE_STARTUP_N(module)    zm_startup_##module

YAR_STARTUP(packager) 展开之后是这样的：

zm_startup_yar_packager(type, module_number)

如果用 zm_startup_yar_packager 在 Yar 源码中是搜不到结果的，这是因为宏只有在编译的时候才会展开，那么为什么用 YAR_STARTUP(packager) 也搜不到呢？

因为在定义函数名的时候用的不是 YAR_STARTUP，而是 YAR_STARTUP_FUNCTION，先来看看定义：

#define YAR_STARTUP_FUNCTION(module)    ZEND_MINIT_FUNCTION(yar_##module)

#define ZEND_MINIT_FUNCTION    ZEND_MODULE_STARTUP_D

/* Declaration macros */
#define ZEND_MODULE_STARTUP_D(module)    zend_result ZEND_MODULE_STARTUP_N(module)(INIT_FUNC_ARGS)

/* Name macros */
#define ZEND_MODULE_STARTUP_N(module)    zm_startup_##module

可以看到，最终使用的都是 ZEND_MODULE_STARTUP_N，它还有一个相似的宏：ZEND_MODULE_STARTUP_D，不同的是，前者是用于命名的宏，无参数，而后者是用于声明/定义的宏，有参数。

在 YAR_STARTUP_FUNCTION(packager) 函数中，先调用 php_yar_packager_register 函数往 Yar 编码模块中注册编码方式，然后往 PHP 中注册编码模块相关的 PHP 常量。

// source：yar_packager.c

YAR_STARTUP_FUNCTION(packager) {
  // 注册编码方式
#ifdef ENABLE_MSGPACK
  php_yar_packager_register(&yar_packager_msgpack);
#endif
  php_yar_packager_register(&yar_packager_php);
  php_yar_packager_register(&yar_packager_json);

  // 注册编码模块相关的 PHP 常量
  REGISTER_STRINGL_CONSTANT("YAR_PACKAGER_PHP", YAR_PACKAGER_PHP, sizeof(YAR_PACKAGER_PHP)-1, CONST_CS|CONST_PERSISTENT);
  REGISTER_STRINGL_CONSTANT("YAR_PACKAGER_JSON", YAR_PACKAGER_JSON, sizeof(YAR_PACKAGER_JSON)-1, CONST_CS|CONST_PERSISTENT);
#ifdef ENABLE_MSGPACK
  REGISTER_STRINGL_CONSTANT("YAR_PACKAGER_MSGPACK", YAR_PACKAGER_MSGPACK, sizeof(YAR_PACKAGER_MSGPACK)-1, CONST_CS|CONST_PERSISTENT);
#endif

  return SUCCESS;
}

接着我们来了解一下注册编码方式的逻辑，Yar 在编码模块中定义了一个结构体 yar_packagers_list，用于存储所有可用的编码方式。

// source：yar_packager.c

struct _yar_packagers_list {
    unsigned int size;
    unsigned int num;
    const yar_packager_t **packagers;
} yar_packagers_list;

结构体字段说明：

  • size：packagers 数组的大小。
  • num：packagers 数组中编码方式的数量。
  • packagers：编码方式的指针数组。

在 php_yar_packager_register 函数中，对 yar_packagers_list 进行初始化、扩容及注册编码方式等操作。

// source：yar_packager.c

PHP_YAR_API int php_yar_packager_register(const yar_packager_t *packager) {

    if (!yar_packagers_list.size) {
       // size 为 0，说明未初始化
       // 设置 size 初始值为 5，并为 packagers 分配相应的内存
       yar_packagers_list.size = 5;
       yar_packagers_list.packagers = (const yar_packager_t **)malloc(sizeof(yar_packager_t *) * yar_packagers_list.size);
    } else if (yar_packagers_list.num == yar_packagers_list.size) {
       // num 等于 size，说明数组已经满了，需要进行扩容
       yar_packagers_list.size += 5;
       yar_packagers_list.packagers = (const yar_packager_t **)realloc(yar_packagers_list.packagers, sizeof(yar_packager_t *) * yar_packagers_list.size);
    }
    
    // 将编码方式存储到 packagers 数组下标为 num 处
    yar_packagers_list.packagers[yar_packagers_list.num] = packager;

    // 返回存储编码方式的索引位置并加一
    return yar_packagers_list.num++;
}

激活编码模块

每次请求进来到达请求初始化阶段时，就会调用 YAR_ACTIVATE_FUNCTION(packager) 函数设置本次请求使用的编码方式。

// source：yar_packager.c

YAR_ACTIVATE_FUNCTION(packager) {
    // 获取默认的编码方式
    const yar_packager_t *packager = php_yar_packager_get(YAR_G(default_packager), strlen(YAR_G(default_packager)));

    if (packager) {
        // 获取成功则直接设置为默认编码方式，并返回
        YAR_G(packager) = packager;
        return SUCCESS;
    }

    // 如果没有默认编码方式，则使用 PHP 作为默认的编码方式，并输出警告信息
    YAR_G(packager) = &yar_packager_php;
    php_error(E_WARNING, "unable to find package '%s', use php instead", YAR_G(default_packager));

    return SUCCESS;
}

调用编码模块

前面两个阶段都属于初始化的阶段，只有执行脚本的阶段才会去调用编码、解码函数，那么什么时候会调用呢？

上一篇文章中有提到 Yar 支持两种数据传输方式：HTTP、TCP。无论使用哪种传输方式，都会在发送请求前和收到响应后调用编码模块。

为此，Yar 提供了两个通用函数：php_yar_packager_pack、php_yar_packager_unpack，用于对数据进行编码或解码操作。

php_yar_packager_pack

php_yar_packager_pack 函数只需要传入编码方式的名称和需要编码的数据，就可以使用对应的编码方式对数据进行编码。

// source：yar_packager.c

zend_string *php_yar_packager_pack(char *packager_name, zval *pzval, char **msg) {
    char header[8];
    smart_str buf = {0};
    
    // 获取编码方式，如果传入的名称为 null，则使用默认的编码方式
    const yar_packager_t *packager = packager_name ?
        php_yar_packager_get(packager_name, strlen(packager_name)) : YAR_G(packager);

    if (!packager) {
        php_error_docref(NULL, E_ERROR, "unsupported packager %s", packager_name);
        return 0;
    }
    
    // 将编码方式的名称写入前 8 个字节中
    memcpy(header, packager->name, 8);
    smart_str_alloc(&buf, YAR_PACKAGER_BUFFER_SIZE /* 1M */, 0);
    smart_str_appendl(&buf, header, 8);
    
    // 调用具体的编码函数
    packager->pack(packager, pzval, &buf, msg); 

    if (buf.s) {
        // 如果编码成功，则在末尾加上 \0
        smart_str_0(&buf);
        return buf.s;
    }

    // 编码失败则释放 buf 并返回 null
    smart_str_free(&buf);

    return NULL;
}

如果使用 JSON 编码方式，那么 packager->pack 实际上调用的是 php_yar_packager_json_pack 函数，将数据编码为 JSON 字符串。

php_yar_packager_unpack

php_yar_packager_unpack 函数不像 php_yar_packager_pack 函数直接传入编码方式的名称，而是传入需要解码的数据及数据的长度，通过取数据前 8 字节得到编码方式的名称，然后通过编码方式的名称获取编码方式，最后调用真正的解码函数对数据进行解码。

// source：yar_packager.c

zval * php_yar_packager_unpack(char *content, size_t len, char **msg, zval *ret) {
    char *pack_info = content; /* 4 bytes, last byte is version */
    const yar_packager_t *packager;

    // 数据往后移动 8 字节，就是之前提到的 payload
    content = content + 8;
    len -= 8;
    
    // 编码方式的名称虽然占用了 8 字节，实际上只用了 7 字节，第 8 个字节存储 \0
    *(pack_info + 7) = '\0';

    // 获取编码方式
    packager = php_yar_packager_get(pack_info, 7);

    if (!packager) {
        spprintf(msg, 0, "unsupported packager '%s'", pack_info);
        return NULL;
    }
    
    // 调用具体的解码函数
    return packager->unpack(packager, content, len, msg, ret);

}

如果使用 JSON 编码方式，那么 packager->unpack 实际上调用的是 php_yar_packager_json_unpack 函数，将数据（JSON 字符串）解码并存储到 ret 中。

关闭编码模块

当执行完 PHP 脚本后，进入请求关闭阶段清理执行脚本过程中使用到的资源。在此之后，如果是 PHP-FPM 模式下，则会进入请求初始化阶段等待下一次请求到来，停止 PHP-FPM 时才会进入模块关闭阶段；如果是 PHP-Cli 模式会直接进入到模块关闭阶段。

关闭编码模块的逻辑很简单，只需要释放 yar_packagers_list 中 packagers 使用的内存就可以了。

// source：yar_packager.c

YAR_SHUTDOWN_FUNCTION(packager) {
    if (yar_packagers_list.size) {
        free(yar_packagers_list.packagers);
    }
    return SUCCESS;
}

总结

在本文中，基于 PHP 生命周期介绍了各个阶段中编码模块都做了些什么，在下一篇文章中将会介绍 Yar 的传输模块，通过该模块，我们就可以知道编码后的数据是怎样被发送出去的。

这篇文章断断续续花费了一个月的时间，期间经历了被裁员、离职、面试等等，心情也是跌宕起伏。之前换工作都是无缝衔接，中间也没休息过，所以这次就当放了个假，休息休息。这几天在家做做饭、搞搞卫生，感觉也还不错，在家待了几天后，想着抓紧把 Yar 系列写完，好准备下一个系列的文章。

至于工作，这段时间也面试了几家，如果没有合适的话，那就明年再战。

:)

]]> Yar 源码阅读笔记：RPC 通信协议 https://her-cat.com/posts/2021/11/03/yar-internals-protocol/ Wed, 03 Nov 2021 16:48:08 +0800 https://her-cat.com/posts/2021/11/03/yar-internals-protocol/ 在上一篇文章中简单的介绍了 Yar 的基本功能，今天我们来了解一下 Yar 的通信协议。 前言

在上一篇文章中简单的介绍了 Yar 的基本功能，今天我们来了解一下 Yar 的通信协议。

通信协议是服务端与客户端之间进行数据交换的一种约定，只有遵循这种约定才能进行通信。

Yar 支持两种数据传输方式：HTTP、TCP。

  • HTTP：使用 curl 传输 HTTP 协议数据。
  • TCP：使用 socket 传输 TCP 协议数据。

HTTP 本身就是一种服务端与客户端通信的协议，Yar 为什么还要自定义通信协议呢？

为什么要自定义通信协议？

Yar 直接使用 HTTP 协议进行数据传输是没有任何问题的，因为 HTTP 协议是建立在 TCP 协议之上的应用层协议，其协议本身已经清楚的定义了数据的边界，能够保证客户端/服务端正常地收发每一个数据包。

但是，Yar 数据传输方式除了 HTTP 协议以外还支持 TCP 协议，当 Yar 使用 TCP 协议传输数据时，就必须自己定义一个基于 TCP 协议的应用层协议了。

因为 TCP 是一个基于字节流的传输层通信协议，重点在于它是一个流式协议，也就是说数据与数据之间没有明确的边界，它只需要保证数据能够高效、可靠地将数据从一端传输到另一端。

可以把 TCP 想像成一根水管，数据是水管中的水，传输就是水在水管中从一端到另一端的过程。从水管一端接水的时候，你只知道桶里已经接了多少水，但是你根本不知道水管中还有多少水，只能一直等着。如果水突然停了，你也分不清数据到底是被分为多次发送，还是发送完了。

所以自定义通信协议主要目的是为了让接水的人知道本次接水的动作什么时候结束，也就是让客户端/服务端能够辨别出每一个数据包的边界。

这也是网友们常常提到的 TCP「粘包」问题，其实跟 TCP 一点关系都没有，这个问题是由于程序员在设计通信协议时，没有定义清楚数据之间的边界导致的。

常见的协议格式

有以下几种常见的协议格式：

  • 特殊字符作为边界
  • 显式编码数据长度
  • 固定数据包大小

特殊字符作为边界

这种方式是在协议中设置特殊字符作为数据的边界，比如 \r、\n、\0 等等。

HTTP 就是一个很好的例子，HTTP 将 \r\n 作为数据的边界。如果是 GET 请求，当读取到两个连续的 \r\n 时，说明一个完整的 HTTP 数据包结束了。

代码实现可以参考我之前写的《浅入浅出 HTTP》中 GET 请求的部分。

显式编码数据长度

显式编码数据长度就是在协议中提前将要发送的数据长度告诉接收方。

接收方在读取数据的时候，就可以先读取发送的数据长度，然后开始一直读取数据，当已读取的数据长度等于发送的数据长度时，停止读取数据。

HTTP 协议除了使用特殊字符作为边界，还使用了显式编码数据长度这种方式。当 HTTP 请求为 POST 或其它需要 body 的方式时，就会读取请求头中的 Content-Length 字段，来确定 body 的长度。

代码实现可以参考我之前写的《浅入浅出 HTTP》中 POST 请求的部分，也可以阅读《使用 Workerman 接入 Bilibili 直播弹幕协议》中对于协议声明及处理。

固定数据包长度

固定数据包长度的方式跟前一种有点像，但是丢弃了数据头部的长度字段，而是将数据包设为固定长度，属于前者的阉割版本。

这样接收方用规定的数据包长度去接收每一个数据包即可。不过这种方式用的较少，一般用来传输某些固定大小的指令时才会用到。

Yar 协议格式

Yar 的通信协议分为 header 和 body 两个部分，其中，body 由 packager_name（编码方式名称）和 payload（数据）组成。

下面分别对这几部分进行说明。

header 部分

header 中存储了 Yar 通信协议的基本信息，比如请求 ID、协议版本、调用方等等。

当然，最重要就是存储了 body 部分数据的长度。所以 Yar 使用的是显式编码数据长度方式。

Yar 定义了 _yar_header 结构体，用来存储 header 的信息。

// source: yar_protocol.h

typedef struct _yar_header {
    uint32_t       id;          // 4 字节
    uint16_t       version;     // 2 字节
    uint32_t       magic_num;   // 4 字节
    uint32_t       reserved;    // 4 字节
    unsigned char  provider[32];// 32 字节
    unsigned char  token[32];   // 32 字节
    uint32_t       body_len;    // 4 字节
} __attribute__ ((packed)) yar_header_t;

结构体中字段说明：

  • id：唯一请求 ID。
  • version：协议版本，默认为 0。
  • magic_num：用于验证请求有效性的特殊值，默认为 0x80DFEC60。
  • reserved：预留参数，可以用来存储一些请求参数。
  • provider：客户端的名字。
  • token：预留参数，可以用来做 API key 验证。
  • body_len: 用于存储 body 的长度。

header 的总长度为 82 字节（设置了内存对齐）。

packager_name 部分

package_name 就是编码方式的名称。因为 Yar 支持多种消息编码方式，所以在 header 后面预留了 8 个字节，用于存储编码方式的名称，比如 JSON、MSGPACK、PHP。

服务端在收到消息后，就可以知道 payload 是通过哪种方式进行编码的，然后就可以使用对应的方式进行解码。

注意：编码方式名称的 8 个字节是固定的。

payload 部分

payload 是 RPC 传输的数据，数据分为两种：请求数据和响应数据。payload 的数据长度是动态变化的，可以通过 header 中的 body_len 得知。

请求数据

Yar 定义了一个 yar_request_t 结构体，用于在 Yar 内部传递请求数据。

// source: yar_request.h

typedef struct _yar_request {
	zend_ulong id;
	zend_string *method;
	zval parameters;
	zval options;
} yar_request_t;

yar_request_t 结构体字段说明：

  • id: 请求 ID。
  • method：被调用的方法。
  • parameters：参数。
  • options：可选项，例如请求超时时间、编码方式名称等，该参数不会被打包传输。

在发送请求前会调用 php_yar_request_pack 函数，将 yar_request_t 中的请求 ID、被调用的方法、参数存储一个 hash 字典中。

// source: yar_request.c

zend_string *php_yar_request_pack(yar_request_t *request, char **msg) {
	zval rv;
	zend_array req;
	zend_string *payload;
	char *packager_name = NULL;

	// 尝试从 options 中取出设置的编码方式名称
	if (IS_ARRAY == Z_TYPE(request->options)) {
		zval *pzval;
		if ((pzval = zend_hash_index_find(Z_ARRVAL(request->options), YAR_OPT_PACKAGER)) && IS_STRING == Z_TYPE_P(pzval)) {
			packager_name = Z_STRVAL_P(pzval);
		}
	}

	// 初始化一个 hash 字典
	zend_hash_init(&req, 8, NULL, NULL, 0);

	// 将请求 ID 赋值给临时变量 rv
	ZVAL_LONG(&rv, request->id);
	// 以字符 i 作为 key，将 rv 中的请求 ID 存储到 hash 字典中
	zend_hash_add(&req, ZSTR_CHAR('i'), &rv);

	// 将被调用的方法赋值给临时变量 rv
	ZVAL_STR(&rv, request->method);
	// 以字符 m 作为 key，将 rv 中的请求 ID 存储到 hash 字典中
	zend_hash_add(&req, ZSTR_CHAR('m'), &rv);
	
	// 如果参数的类型为数组，则以字符 p 作为 key，将参数存储到 hash 字典中；
	// 否则初始化一个空字典存储到 hash 字典中
	if (IS_ARRAY == Z_TYPE(request->parameters)) {
		zend_hash_add(&req, ZSTR_CHAR('p'), &request->parameters);
	} else {
		zend_array empty_arr;
		zend_hash_init(&empty_arr, 0, NULL, NULL, 0);
		ZVAL_ARR(&rv, &empty_arr);
		zend_hash_add(&req, ZSTR_CHAR('p'), &rv);
	}

	// 调用编码器将 hash 字典进行编码处理
	ZVAL_ARR(&rv, &req);
	if (!(payload = php_yar_packager_pack(packager_name, &rv, msg))) {
		zend_hash_destroy(&req);
		return NULL;
	}

	// 释放 hash 字典
	zend_hash_destroy(&req);

	// 返回编码后的数据
	return payload;
}

上面的 hash 字典是 PHP 数组的底层实现，所以请求数据实际上是一个数组，数组的 key 是字段的首字母：

$request = [
    "i" => "123" ,                  // 请求 ID
    "m" => "login" ,                // 被调用的方法
    "p" => ["her-cat", "123456"],   // 参数
];

假设使用 JSON 方式对请求数据进行编码，那么编码过后得到的 JSON 字符串就是 payload 的内容：

{"i":"123","m":"login","p":["her-cat","123456"]}

包含请求数据的 RPC 通信协议格式：

服务端收到请求数据后，使用 JSON 方式进行解码就可以得到 $request 这样的数组。

响应数据

同样，对于响应数据，Yar 也定义了一个 yar_response_t 结构体。

typedef struct _yar_response {
	long id;
	int  status;
	zend_string *out;
	zval err;
	zval retval;
} yar_response_t;

yar_response_t 结构体字段说明：

  • id：同请求 ID。
  • status：状态，用于判断被调用的方法执行是否成功。
  • out：服务端输出的内容。
  • err: 错误或异常信息，通过 status 可以知道 err 的内容类型。
  • retval：被调用方法的返回值。

status 字段有以下几种值：

#define YAR_ERR_OKEY      		0x0     // 执行成功
#define YAR_ERR_PACKAGER  		0x1     // 编码相关错误
#define YAR_ERR_PROTOCOL  		0x2     // 协议相关错误
#define YAR_ERR_REQUEST   		0x4     // 请求相关错误
#define YAR_ERR_OUTPUT    		0x8     // 输出相关错误
#define YAR_ERR_TRANSPORT 		0x10    // 数据传输相关错误
#define YAR_ERR_FORBIDDEN 		0x20    // 不允许访问
#define YAR_ERR_EXCEPTION 		0x40    // 发生异常
#define YAR_ERR_EMPTY_RESPONSE 	0x80    // 响应内容为空

在执行被调用方法完成后，会调用 php_yar_server_response 函数将 yar_response_t 中的数据存储到一个 hash 字典中。

static void php_yar_server_response(yar_request_t *request, yar_response_t *response, char *pkg_name) {
	zval rv;
	char *err_msg;
	zend_array ret;
	zend_string *payload;
	yar_header_t header = {0};

	zend_hash_init(&ret, 8, NULL, NULL, 0);

	ZVAL_LONG(&rv, response->id);
	zend_hash_add(&ret, ZSTR_CHAR('i'), &rv);
	ZVAL_LONG(&rv, response->status);
	zend_hash_add(&ret, ZSTR_CHAR('s'), &rv);

	if (response->out && ZSTR_LEN(response->out)) {
		ZVAL_STR(&rv, response->out);
		zend_hash_add(&ret, ZSTR_CHAR('o'), &rv);
	}
	if (!Z_ISUNDEF(response->retval)) {
		zend_hash_add(&ret, ZSTR_CHAR('r'), &response->retval);
	}
	if (!Z_ISUNDEF(response->err)) {
		zend_hash_add(&ret, ZSTR_CHAR('e'), &response->err);
	}

	
	// ...省略部分代码
}

与请求数据的处理逻辑差不多，最终会得到一个存储响应数据的数组，类似于下面这样：

$response = [
    "i" => "123",       // 请求 ID
    "s" => "0" ,        // 状态
    "r" => "success",   // 返回值
    "o" => "",          // 输出
    "e" => "",          // 错误或异常
];

使用 JSON 方式进行编码后得到 payload：

{"i":"123","s":"0","r":"success","o":"","e":""}

包含响应数据的 RPC 通信协议格式：

客户端收到响应数据后，使用 JSON 方式解码得到的也是这样一个数组。

通过状态判断执行结果，如果执行失败，获取错误或异常信息并抛出；执行成功则将返回值返回给调用方。

总结

通过本文，让我们对于 Yar 的通信协议有了一定的了解。先解释了为什么 Yar 需要自定义通信协议，并列举了常见的协议格式，然后详细地介绍了 Yar 通信协议中的内容及作用。

]]> Yar 源码阅读笔记：开篇 https://her-cat.com/posts/2021/10/17/yar-internals-start/ Sun, 17 Oct 2021 23:38:04 +0800 https://her-cat.com/posts/2021/10/17/yar-internals-start/ Yar（yet another RPC framework,）是鸟哥在 2012 年开发的一个轻量级的并行 RPC 框架，支持多种编码方式（JSON、msgpack、PHP）及 HTTP、TCP 两种数据传输方式 前言

本文是 Yar 源码系列的第一篇文章，主要介绍 Yar 以及服务端、客户端的基本使用，详细的源码分析会放在后续的文章中。

为什么要研究 Yar？

我从 8 月初开始阅读 《PHP 7底层设计与源码实现》这本书，直到前一阵子才看完，算是通读了一遍。看完之后总想着动手实操一番，将书中的理论知识赋予实践，做到理论实践相结合。

在挑选研究项目的时候，有以下几个可选项：

Swoole/Swow 是 PHP 高性能协程的网络通信引擎，从语言上来讲，前者由 C++ 编写，后者主要由 C 语言编写，一部分逻辑用 PHP 实现。从编码风格、代码实现来说，我更喜欢后者，虽然公司主要用的 Swoole 框架…

没有选 Swoole/Swow 的原因是，这两个项目包含了网络编程、并发编程、多进程/线程、进程间通信等多项技术，它们支持的功能特性也非常多，讲清楚这些功能的实现也需要花费不少的功夫，不符合我们小而美的目标。

所以在权衡了一阵之后，最终选择了 Yar。

Yar 介绍

Yar（yet another RPC framework,）是鸟哥（laruence）在 2012 年开发的一个轻量级的并行 RPC 框架，支持多种编码方式（JSON、msgpack、PHP）及 HTTP、TCP 两种数据传输方式，最重要的是支持并行调用，可以让多个数据源并行处理，从而提高系统的性能。

Yar 服务端

下面是一个 Yar 服务端的例子：

class User
{
    /**
     * 用户登录
     * @param string $username 用户名
     * @param string $password 密码
     * @return string
     */
    public function login(string $username, string $password): string
    {
        return 'success';
    }
}

$server = new Yar_Server(new User());
$server->handle();

在上面的例子中，定义了一个 User 类，并简单地实现了一个 login 方法，然后实例化 User 类并传入到 Yar_Server 的构造函数中，随后调用 Server 中的 handle 方法，处理即将到来的请求。

在 handle 方法中，通过判断请求方式执行不同的操作。

当请求方式为 POST 时，将会执行 RPC 远程服务 的逻辑：对请求数据进行解析、校验，拿到被调用的方法名称及参数后，执行该方法并响应结果。

当请求方式为非 POST 方式时，输出 RPC 服务的 API 信息。如果在 php.ini 中设置了 yar.expose_info = 0，表示不公开信息，将会抛出 “不允许访问服务信息” 的异常。

将上述的例子保存为 server.php，然后执行 php -S 127.0.0.1:3000 启动 PHP 自带的 Web 服务。

在浏览器中输入 http://127.0.0.1:3000 ，打开服务端 API 信息页面：

从页面中我们可以看到这个 RPC 服务支持的方法列表及方法名称、参数、注释信息。

Yar 客户端

Yar 客户端支持同步调用、并行调用两种方式。

  • 同步调用也就是串行调用，必须前一个请求执行完才能执行下一个请求，不能充分的利用系统资源。
  • 并行调用顾名思义就是能够同时执行多个请求，不需要等待某个请求结束再执行，请求完成后会运行指定的回调函数。

当然，客户端还支持一些其它的特性，例如：请求持久化、自定义 DNS、HTTP 代理等，这些特性的使用方法可以在官方文档中找到，这里就不赘述了。

同步调用

Yar 的同步调用非常简单，就像调用本地方法一样：

// 实例化客户端
$client = new Yar_Client("http://127.0.0.1:3000/server.php");

// 设置超时时间
$client->SetOpt(YAR_OPT_CONNECT_TIMEOUT, 1000);

// 调用 login 方法
$result = $client->login("her-cat", "123456");

var_dump($result);


// 输出：string(7) "success"

并行调用

并行调用的使用方式跟同步调用有一点点区别，调用远程方法时需要通过并行客户端中的 call 方法，并传入相应的回调函数，当请求完成时就会调用该回调函数。

function callback($ret, $callInfo) {
    var_dump($ret, $callInfo);
}

function error_callback($type, $error, $callInfo) {
    error_log($error);
}

$url = 'http://127.0.0.1:3000/server.php';

Yar_Concurrent_Client::call($url, 'login', ['her-cat', '123456'], 'callback', 'error_callback');
Yar_Concurrent_Client::call($url, 'login', ['her-cat', '123456'], 'callback', 'error_callback');
Yar_Concurrent_Client::call($url, 'login', ['her-cat', '123456'], 'callback', 'error_callback', [YAR_OPT_TIMEOUT => 1]);

Yar_Concurrent_Client::loop();

可以看到传入的参数除了 callback 以外，还传入了 error_callback 回调函数，当服务端执行方法的过程中发生了错误，就会运行 error_callback 回调函数。

总结

到这里本文就结束了，后续就会开始从源码的角度去分析这些功能是如何实现的。

Goodbye~

]]> PHP 源码阅读笔记：编译与调试 PHP https://her-cat.com/posts/2021/08/06/php-internals-compile-and-debugging/ Fri, 06 Aug 2021 18:52:15 +0800 https://her-cat.com/posts/2021/08/06/php-internals-compile-and-debugging/ 工欲善其事必先利其器。 基本信息
  • PHP 版本：7.1.0
  • 调试环境：Ubuntu（WSL）
  • 调试工具：GDB、Clion

编译 PHP

下载并安装 PHP：

$ wget http://cn2.php.net/distributions/php-7.1.0.tar.gz
$ tar -xzvf php-7.1.0.tar.gz
$ cd php-7.1.0
$ ./configure --prefix=$HOME/php-7.1.0/build --enable-fpm

注意：$HOME/php-7.1.0/build 是 PHP 执行文件和库文件安装的目录，可以自定义。--enable-fpm 表示同时安装 php-fpm。

接下来修改编译优化等级，方便我们在调试的过程中查看变量的内容。

首先在 php-7.1.0/Makefile 文件中搜索 CFLAGS_CLEAN，然后将 -02 改为 -o0，表示不需要优化。

CFLAGS_CLEAN = -I/usr/include -g -O0 -fvisibility=hidden -DZEND_SIGNALS $(PROF_FLAGS)

执行 make 命令：

$ make && make install

执行完成后，就可以在 php-7.1.0/build/bin 目录下看到 PHP 相关的可执行文件了。

pear  peardev  pecl  phar  phar.phar  php  php-cgi  php-config  phpdbg  phpize

调试 PHP

使用 Clion 进行调试

首先用 Clion 打开 php-7.1.0 目录，Clion 会在根目录下自动创建 CMakeLists.txt 文件，复制下面的内容覆盖 CMakeLists.txt 中的内容：

cmake_minimum_required(VERSION 3.10)

project(php_7_1_0)

set(CMAKE_CXX_STANDARD 14)

set(PHP_SOURCE .)

file(GLOB_RECURSE HEAD_FILES FOLLOW_SYMLINKS ${PHP_SOURCE})
file(GLOB_RECURSE HEAD_FILES FOLLOW_SYMLINKS ${PHP_SOURCE}/ext)
file(GLOB_RECURSE HEAD_FILES FOLLOW_SYMLINKS ${PHP_SOURCE}/Zend)
file(GLOB_RECURSE HEAD_FILES FOLLOW_SYMLINKS ${PHP_SOURCE}/sapi)
file(GLOB_RECURSE HEAD_FILES FOLLOW_SYMLINKS ${PHP_SOURCE}/pear)
file(GLOB_RECURSE HEAD_FILES FOLLOW_SYMLINKS ${PHP_SOURCE}/TSRM)

file(GLOB_RECURSE SRC_LIST FOLLOW_SYMLINKS
        ${PHP_SOURCE}/*.c
        ${PHP_SOURCE}/ext/*.c
        ${PHP_SOURCE}/main/*.c
        ${PHP_SOURCE}/Zend/*.c
        ${PHP_SOURCE}/sapi/*.c
        ${PHP_SOURCE}/pear/*.c
        ${PHP_SOURCE}/TSRM/*.c
)

include_directories(${PHP_SOURCE})
include_directories(${PHP_SOURCE}/ext)
include_directories(${PHP_SOURCE}/main)
include_directories(${PHP_SOURCE}/Zend)
include_directories(${PHP_SOURCE}/sapi)
include_directories(${PHP_SOURCE}/pear)
include_directories(${PHP_SOURCE}/TSRM)

add_executable(${PROJECT_NAME} ${SRC_LIST})
add_custom_target(makefile COMMAND make && make install WORKING_DIRECTORY ${PROJECT_SOURCE_DIR})

注意：/home/ubuntu/php-7.1.0 要替换成你自己的 PHP 所在的路径。

点击右上角绿色锤子旁边的下拉框 => Edit Configurations => makefile，按照下面的步骤进行操作：

  • Target：makefile（一般不用动）
  • Executable：点击右边的 ... 按钮，选择 php-7.1.0/bin/php 文件
  • Program arguments：输入你要调试的 PHP 脚本的文件名，比如 index.php
  • Working directory：选择上面 PHP 脚本所在的目录
  • 删除 Before launch 中的 Build，避免每次调试都重新构建 PHP

点击右上角绿色的小虫子或者使用快捷键 Shift + F9 开始调试

使用 GDB 进行调试

用来测试的 index.php ：

<?php

$a = 'hello';

var_dump($a);

开始 GDB 调试：

gdb /php-7.1.0/build/bin/php

使用 b 命令在 var_dump 处打断点：

(gdb) b zif_var_dump
Breakpoint 1 at 0x48f3bc: file /home/ubuntu/php-7.1.0/ext/standard/var.c, line 200.

为啥这里是 zif_var_dump？

因为 zif_var_dump 是 var_dump 函数的底层实现， 是由 PHP_FUNCITON(var_dump) 宏展开后的名称，所以直接搜 zif_var_dump 是搜不到的。

#define ZEND_FN(name)   zif_##name
#define ZEND_NAMED_FUNCTION(name)   void name(INTERNAL_FUNCTION_PARAMETERS)
#define ZEND_FUNCTION(name) ZEND_NAMED_FUNCTION(ZEND_FN(name))

/* PHP-named Zend macro wrappers */
#define PHP_FUNCTION			ZEND_FUNCTION

PHP_FUNCTION(var_dump)
{
	zval *args;
	int argc;
	int	i;

	if (zend_parse_parameters(ZEND_NUM_ARGS(), "+", &args, &argc) == FAILURE) {
		return;
	}

	for (i = 0; i < argc; i++) {
		php_var_dump(&args[i], 1);
	}
}

开始运行 PHP 文件：

(gdb) r index.php
Starting program: /home/ubuntu/php-7.1.0/build/bin/php index.php
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
Breakpoint 1, zif_var_dump (execute_data=0x7ffffb6130d0, return_value=0x7ffffffea400)
    at /home/ubuntu/php-7.1.0/ext/standard/var.c:200
200     {

代码执行到 zif_var_dump 就停止了，说明命中了断点。我们可以使用 l 命令查看附近的源码：

(gdb) l
195     /* }}} */
196
197     /* {{{ proto void var_dump(mixed var)
198        Dumps a string representation of variable to output */
199     PHP_FUNCTION(var_dump)
200     {
201             zval *args;
202             int argc;
203             int     i;
204

使用 bt 命令查看调用栈：

(gdb) bt
#0  zif_var_dump (execute_data=0x7ffffb6130d0, return_value=0x7ffffffea400)
    at /home/ubuntu/php-7.1.0/ext/standard/var.c:200
#1  0x0000000008642151 in ZEND_DO_ICALL_SPEC_RETVAL_UNUSED_HANDLER ()
    at /home/ubuntu/php-7.1.0/Zend/zend_vm_execute.h:628
#2  0x000000000864038e in execute_ex (ex=0x7ffffb613030) at /home/ubuntu/php-7.1.0/Zend/zend_vm_execute.h:429
#3  0x0000000008640d05 in zend_execute (op_array=0x7ffffb67e000, return_value=0x0)
    at /home/ubuntu/php-7.1.0/Zend/zend_vm_execute.h:474
#4  0x00000000085a2ca6 in zend_execute_scripts (type=8, retval=0x0, file_count=3)
    at /home/ubuntu/php-7.1.0/Zend/zend.c:1474
#5  0x00000000084eb1ce in php_execute_script (primary_file=0x7ffffffecd00) at /home/ubuntu/php-7.1.0/main/main.c:2533
#6  0x0000000008743462 in do_cli (argc=2, argv=0x90c1ef0) at /home/ubuntu/php-7.1.0/sapi/cli/php_cli.c:990
#7  0x000000000874483e in main (argc=2, argv=0x90c1ef0) at /home/ubuntu/php-7.1.0/sapi/cli/php_cli.c:1378

使用 u 命令让代码运行到指定的行：

(gdb) u 209
zif_var_dump (execute_data=0x7ffffb6130d0, return_value=0x7ffffffea400)
    at /home/ubuntu/php-7.1.0/ext/standard/var.c:209
209             for (i = 0; i < argc; i++) {

使用 p 命令打印变量 $a 的值：

(gdb) p args[0].value.str.val
$1 = "h"

使用 @ 指定输出长度：

(gdb) p args[0].value.str.val@5
$2 = {"h", "e", "l", "l", "o"}
]]> Workerman 源码分析：文件上传 https://her-cat.com/posts/2021/05/08/workerman-file-upload/ Sat, 08 May 2021 17:42:00 +0800 https://her-cat.com/posts/2021/05/08/workerman-file-upload/ Workerman 将解析协议这一步进行后置，当程序需要用到 HTTP 协议携带的信息时才会解析相应的数据，并将解析结果 前言

在 Nginx 中 HTTP 数据是一边接收一边进行解析的，如果解析过程中发现收到的数据有问题就会停止解析，并且停止接收数据。

而 Workerman 将解析协议这一步进行后置，当程序需要用到 HTTP 协议携带的信息时才会解析相应的数据，并把解析结果缓存起来，下次获取信息时就直接从缓存中读取即可，避免多次解析。

两种方式各有自己的优点，前者的优点就是可以及时的检查数据是否有问题，后者的优点是在接收数据的逻辑相对要简单一点。

解析上传文件的逻辑在 Request::parseUploadFiles 方法中，下面是它的调用栈。

// source: Protocols\Http\Request.php
post()/file()
    -> parsePost()
        -> parseUploadFiles()

解析 POST 数据

当调用 post 或 file 方法获取 POST 参数或上传的文件时，程序会检查是否已经解析过了，如果已经解析过了则直接返回对应的结果，否则就会调用 parsePost 方法解析数据。

protected function parsePost()
{
    // rawBody() 返回的就是请求体的内容
    $body_buffer = $this->rawBody();
    // 初始化用于保存解析数据的缓存
    $this->_data['post'] = $this->_data['files'] = array();
    if ($body_buffer === '') {
        return;
    }
    // 尝试从缓存中读取
    $cacheable = static::$_enableCache && !isset($body_buffer[1024]);
    if ($cacheable && isset(static::$_postCache[$body_buffer])) {
        $this->_data['post'] = static::$_postCache[$body_buffer];
        return;
    }
    // 读取请求头中的 content-type 字段，如果请求头没有被解析过，那么也会进行解析并缓存
    $content_type = $this->header('content-type', '');
    // 尝试解析 boundary 字段，如果获取到了说明是 multipart/form-data 类型的，可能会上传文件
    if (\preg_match('/boundary="?(\S+)"?/', $content_type, $match)) {
        // $match[1] 中就是我们上面说的边界值
        // 加上 -- 得到请求体中的边界值
        $http_post_boundary = '--' . $match[1];
        $this->parseUploadFiles($http_post_boundary);
        return;
    }
    // 如果从 content-type 中匹配到了 json，比如 application/json
    // 说明请求体的数据是 JSON 格式的
    if (\preg_match('/\bjson\b/i', $content_type)) {
        $this->_data['post'] = (array) json_decode($body_buffer, true);
    } else {
        // 否则就是 application/x-www-form-urlencoded
            \parse_str($body_buffer, $this->_data['post']);
    }
    // 如果开启了缓存，就把解析结果缓存起来
    if ($cacheable) {
        static::$_postCache[$body_buffer] = $this->_data['post'];
        if (\count(static::$_postCache) > 256) {
            unset(static::$_postCache[key(static::$_postCache)]);
        }
    }
}

解析请求体的内容

接下来就是 parseUploadFiles 方法的内容了。

首先处理请求体，删掉末尾的结束边界值，然后通过边界值得到数据块数组。

// 先获取请求体的内容
$http_body = $this->rawBody();
//删除末尾的结束边界值
$http_body = \substr($http_body, 0, \strlen($http_body) - (\strlen($http_post_boundary) + 4))

// 通过边界值 + \r\n 分割请求体，得到数据块数组
$boundary_data_array = \explode($http_post_boundary . "\r\n", $http_body);
if ($boundary_data_array[0] === '') {
    unset($boundary_data_array[0]);
};

为什么计算 substr 结束位置最后要 +4 呢？

因为 结束边界值 = 边界值 + -- + \r\n。

接下来用两个 foreach 和一个 switch case 来解析请求体的内容。

遍历所有的数据块

通过 \r\n\r\n 分割数据块，得到数据块的头部信息和数据块的值，然后去除数据块的值末尾的 \r\n。

foreach ($boundary_data_array as $boundary_data_buffer) {
    list($boundary_header_buffer, $boundary_value) = \explode("\r\n\r\n", $boundary_data_buffer, 2);
    // 去除 $boundary_value 末尾的 \r\n
    $boundary_value = \substr($boundary_value, 0, -2);
    $key++;
}

解析数据块的头部信息

数据块的头部信息可能存在多行，所以需要通过 \r\n 分割头部信息字符串得到头部信息的数组。

然后遍历该数组，在循环中通过 : 分割每行的头部信息，得到字段名 $header_key 和字段值 $header_value 。

foreach (\explode("\r\n", $boundary_header_buffer) as $item) {
    list($header_key, $header_value) = \explode(": ", $item);
    $header_key = \strtolower($header_key);

    switch ($header_key) {
        case "content-disposition":
            // 匹配到了 filename 说明是文件数据
            if (\preg_match('/name="(.*?)"; filename="(.*?)"/i', $header_value, $match)) {
                $error = 0;
                $tmp_file = '';
                // 获取文件大小
                $size = \strlen($boundary_value);
                // 获取上传临时目录
                $tmp_upload_dir = HTTP::uploadTmpDir();
                if (!$tmp_upload_dir) {
                    $error = UPLOAD_ERR_NO_TMP_DIR;
                } else {
                    // 使用 tempnam 函数在临时目录下创建一个唯一文件名的临时文件
                    $tmp_file = \tempnam($tmp_upload_dir, 'workerman.upload.');
                    // 文件创建成功后，将数据块的值写入到文件中
                    if ($tmp_file === false || false == \file_put_contents($tmp_file, $boundary_value)) {
                        $error = UPLOAD_ERR_CANT_WRITE;
                    }
                }
                // 格式化上传的文件信息
                $files[$key] = array(
                    'key' => $match[1], // 表单中的字段名
                    'name' => $match[2], // 文件名称
                    'tmp_name' => $tmp_file, // 临时文件的完整路径
                    'size' => $size, // 文件大小
                    'error' => $error // 错误
                );
                break;
            } else {
                // 未匹配到 filename 说明是 POST 字段，需要解析 $_POST.
                if (\preg_match('/name="(.*?)"$/', $header_value, $match)) {
                    $this->_data['post'][$match[1]] = $boundary_value;
                }
            }
            break;
        case "content-type":
            // 添加文件类型
            $files[$key]['type'] = \trim($header_value);
            break;
    }
}

switch 中的逻辑就是判断 $header_key 的值，然后执行相应的操作。

  • content-disposition: 通过正则判断是否为文件数据，如果是文件就将数据块的值写入临时文件中，否则将字段和值保存到存放 POST 数据的数组中。
  • content-type: 记录文件的类型。
]]> 58021783493571598 56882619875632128