Merge pull request #12 from lisachenko/feature/ffi-preload

Implement definition preloading with FFI preload mode

Author: lisachenko

README.md

@@ -24,13 +24,14 @@ Pre-requisites and initialization
 --------------
 
 As this library depends on `FFI`, it requires PHP>=7.4 and `FFI` extension to be enabled.
-It should work in CLI mode without any troubles, whereas for web mode `preload` mode should be implemented (not done yet), so please configure `ffi.enable` to be `true`.
+It should work in CLI mode without any troubles, whereas for web mode `preload` mode should be activated.
 Also, current version is limited to x64 non-thread-safe versions of PHP.
 
 To install this library, simply add it via `composer`:
 ```shell script
 composer require lisachenko/z-engine
 ```
+To activate a `preload` mode, please add `Core::preload()` call into your script, specified by `opcache.preload`. This call will be done during the server preload and will be used by library to bypass unnecessary C headers processing during each request.
 
 Next step is to init library itself with short call to the `Core::init()`:
 ```php

include/engine_x64_nts.h

@@ -1,3 +1,6 @@
+#define FFI_SCOPE "ZEngine"
+#define FFI_LIB "ZEND_LIBRARY_NAME"
+
 typedef int64_t zend_long;
 typedef uint64_t zend_ulong;
 typedef int64_t zend_off_t;

preload.php

@@ -0,0 +1,21 @@
+<?php
+/**
+ * Z-Engine framework
+ *
+ * @copyright Copyright 2019, Lisachenko Alexander <lisachenko.it@gmail.com>
+ *
+ * This source file is subject to the license that is bundled
+ * with this source code in the file LICENSE.
+ */
+declare(strict_types=1);
+
+include __DIR__.'/vendor/autoload.php';
+
+use ZEngine\Core;
+
+/**
+ * This file should be loaded during the preload stage, which is defined by opcache.preload file.
+ * Either include it manually, or just add following line into your init section.
+ */
+Core::preload();
+

src/Core.php

@@ -15,6 +15,7 @@
 use FFI;
 use FFI\CData;
 use FFI\CType;
+use ZEngine\Macro\DefinitionLoader;
 use ZEngine\System\Compiler;
 use ZEngine\System\Executor;
 
@@ -222,28 +223,44 @@ public static function init()
             throw new \RuntimeException('Only x64 non thread-safe versions of PHP are supported');
         }
 
-        $definition = file_get_contents(__DIR__ . '/../include/engine_x64_nts.h');
-        $macros     = [
-            'ZEND_API'      => '__declspec(dllimport)',
-            'ZEND_FASTCALL' => $isWindowsPlatform ? '__vectorcall' : '',
+        try {
+            $engine = FFI::scope('ZEngine');
+        } catch (FFI\Exception $e) {
+            if (ini_get('ffi.enable') === 'preload' && PHP_SAPI !== 'cli') {
+                throw new \RuntimeException('Preload mode requires that you call Core::preload before');
+            }
+            // If not, then load definitions by hand
+            $definition = file_get_contents(DefinitionLoader::wrap(__DIR__.'/../include/engine_x64_nts.h'));
+            $arguments  = [$definition];
 
-            'ZEND_MAX_RESERVED_RESOURCES' => '6'
-        ];
+            // For Windows platform we should load symbols from the shared php7.dll library
+            if ($isWindowsPlatform) {
+                $arguments[] = 'php7.dll';
+            }
 
-        // Simple macros resolving
-        $definition = strtr($definition, $macros);
-        $arguments  = [$definition];
-
-        // For Windows platform we should load symbols from the shared php7.dll library
-        if ($isWindowsPlatform) {
-            $arguments[] = 'php7.dll';
+            $engine = FFI::cdef(...$arguments);
         }
-        self::$engine = $engine = FFI::cdef(...$arguments);
+        self::$engine = $engine;
+
         assert(!$isThreadSafe, 'Following properties available only for non thread-safe version');
         self::$executor = new Executor($engine->executor_globals);
         self::$compiler = new Compiler($engine->compiler_globals);
     }
 
+    /**
+     * Preloads definition and Core for ffi.preload mode, should be called during preload stage for better performance
+     */
+    public static function preload()
+    {
+        $definition = file_get_contents(DefinitionLoader::wrap(__DIR__.'/../include/engine_x64_nts.h'));
+        $tempFile   = tempnam(sys_get_temp_dir(), 'php_ffi');
+        file_put_contents($tempFile, $definition);
+        FFI::load($tempFile);
+
+        // Performs initialization of properties, otherwise we will get an error about uninitialized properties
+        Core::init();
+    }
+
     /**
      * Internally cast a memory at given pointer to another type
      */
@@ -252,6 +269,45 @@ public static function cast(string $type, CData $pointer): CData
         return self::$engine->cast($type, $pointer);
     }
 
+    /**
+     * Returns the size of given type
+     */
+    public static function sizeof($cType): int
+    {
+        return FFI::sizeof($cType);
+    }
+
+    /**
+     * Returns the size of given type
+     */
+    public static function addr(CData $variable): CData
+    {
+        return FFI::addr($variable);
+    }
+
+    /**
+     * Copies $size bytes from memory area $source to memory area $target.
+     * $source may be any native data structure (FFI\CData) or PHP string.
+     *
+     * @param CData $target
+     * @param mixed $source
+     * @param int $size
+     */
+    public static function memcpy(CData &$target, &$source, int $size): void
+    {
+        FFI::memcpy($target, $source, $size);
+    }
+
+    /**
+     * Creates a PHP string from $size bytes of memory area pointed by
+     * $source. If size is omitted, $source must be zero terminated
+     * array of C chars.
+     */
+    public static function string(CData $source, int $size = 0): string
+    {
+        return FFI::string($source, $size);
+    }
+
     /**
      * Creates a new instance of specific type
      *
@@ -262,6 +318,14 @@ public static function new(string $type, bool $owned = true, bool $persistent =
         return self::$engine->new($type, $owned, $persistent);
     }
 
+    /**
+     * Returns the size of given type
+     */
+    public static function free(CData $variable): void
+    {
+        self::$engine->free($variable);
+    }
+
     /**
      * Returns a CType definition for engine by type name
      *

src/Macro/DefinitionLoader.php

@@ -0,0 +1,103 @@
+<?php
+/**
+ * Z-Engine framework
+ *
+ * @copyright Copyright 2019, Lisachenko Alexander <lisachenko.it@gmail.com>
+ *
+ * This source file is subject to the license that is bundled
+ * with this source code in the file LICENSE.
+ *
+ */
+declare(strict_types=1);
+
+namespace ZEngine\Macro;
+
+use php_user_filter as PhpStreamFilter;
+use RuntimeException;
+
+class DefinitionLoader extends PhpStreamFilter
+{
+    /**
+     * Default PHP filter name for registration
+     */
+    private const FILTER_IDENTIFIER = 'z-engine.def.loader';
+
+    /**
+     * String buffer
+     */
+    private string $data = '';
+
+    /**
+     * {@inheritdoc}
+     */
+    public function filter($in, $out, &$consumed, $closing)
+    {
+        while ($bucket = stream_bucket_make_writeable($in)) {
+            $this->data .= $bucket->data;
+        }
+
+        if ($closing || feof($this->stream)) {
+            $consumed = strlen($this->data);
+
+            // Simple macros resolving via strtr
+            $transformedData = strtr($this->data, $this->resolveSystemMacros());
+
+            $bucket = stream_bucket_new($this->stream, $transformedData);
+            stream_bucket_append($out, $bucket);
+
+            return PSFS_PASS_ON;
+        }
+
+        return PSFS_FEED_ME;
+    }
+
+    /**
+     * Wraps given filename with stream resolver
+     *
+     * @param string $filename
+     */
+    public static function wrap(string $filename): string
+    {
+        // Let's perform self-registration on first query
+        if (!in_array(self::FILTER_IDENTIFIER, stream_get_filters(), true)) {
+            self::register();
+        }
+
+        return 'php://filter/read=' . self::FILTER_IDENTIFIER . '/resource=' . $filename;
+    }
+
+    /**
+     * Register current loader as stream filter in PHP
+     *
+     * @throws RuntimeException If registration was failed
+     */
+    private static function register(): void
+    {
+        $result = stream_filter_register(self::FILTER_IDENTIFIER, self::class);
+        if ($result === false) {
+            throw new RuntimeException('Stream filter was not registered');
+        }
+    }
+
+    private function resolveSystemMacros(): array
+    {
+        $isThreadSafe      = ZEND_THREAD_SAFE;
+        $isWindowsPlatform = stripos(PHP_OS, 'WIN') === 0;
+        $is64BitPlatform   = PHP_INT_SIZE === 8;
+
+        // TODO: support ts/nts x86/x64 combination
+        if ($isThreadSafe || !$is64BitPlatform) {
+            throw new \RuntimeException('Only x64 non thread-safe versions of PHP are supported');
+        }
+
+        $macros = [
+            'ZEND_API'      => '__declspec(dllimport)',
+            'ZEND_FASTCALL' => $isWindowsPlatform ? '__vectorcall' : '',
+
+            'ZEND_MAX_RESERVED_RESOURCES' => '6',
+            'ZEND_LIBRARY_NAME'           => $isWindowsPlatform ? 'php7.dll' : '',
+        ];
+
+        return $macros;
+    }
+}

src/Reflection/FunctionLikeTrait.php

@@ -12,7 +12,6 @@
 
 namespace ZEngine\Reflection;
 
-use FFI;
 use FFI\CData;
 use ZEngine\Core;
 use ZEngine\Type\OpLine;
@@ -79,18 +78,18 @@ public function redefine(\Closure $newCode): void
         $hash = $this->getHash();
         if (!isset(self::$originalEntries[$hash])) {
             $pointer = Core::new('zend_function *', false);
-            FFI::memcpy(FFI::addr($pointer), $this->pointer, FFI::sizeof($this->pointer));
+            Core::memcpy(Core::addr($pointer), $this->pointer, Core::sizeof($this->pointer));
             self::$originalEntries[$hash] = $pointer;
         }
         $selfExecutionState = Core::$executor->getExecutionState();
         $newCodeEntry       = $selfExecutionState->getArgument(0)->getRawObject();
         $newCodeEntry       = Core::cast('zend_closure *', $newCodeEntry);
 
         // Copy only common op_array part from original one to keep name, scope, etc
-        FFI::memcpy($newCodeEntry->func, $this->pointer[0], FFI::sizeof($newCodeEntry->func->common));
+        Core::memcpy($newCodeEntry->func, $this->pointer[0], Core::sizeof($newCodeEntry->func->common));
 
         // Replace original method with redefined closure
-        FFI::memcpy($this->pointer, FFI::addr($newCodeEntry->func), FFI::sizeof($newCodeEntry->func));
+        Core::memcpy($this->pointer, Core::addr($newCodeEntry->func), Core::sizeof($newCodeEntry->func));
 
     }
 
@@ -128,7 +127,7 @@ public function getOpCodes(): iterable
             $totalOpcodes = $this->pointer->op_array->last;
             while ($opcodeIndex < $totalOpcodes) {
                 $opCode = new OpLine(
-                    FFI::addr($this->pointer->op_array->opcodes[$opcodeIndex++])
+                    Core::addr($this->pointer->op_array->opcodes[$opcodeIndex++])
                 );
                 yield $opCode;
             }