rfc:ffi

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:ffi [2018/12/04 21:19] – dmitryrfc:ffi [2020/08/01 23:54] (current) – RFC was implemented carusogabriel
Line 3: Line 3:
   * Date: 2018-12-04   * Date: 2018-12-04
   * Author: Dmitry Stogov, dmitry@zend.com   * Author: Dmitry Stogov, dmitry@zend.com
-  * Status: Under Discussion+  * Status: Implemented (in PHP 7.4)
   * First Published at: https://wiki.php.net/rfc/ffi   * First Published at: https://wiki.php.net/rfc/ffi
  
Line 10: Line 10:
  
 ===== Proposal ===== ===== Proposal =====
-It is proposed to extend PHP with a simple FFI API designed after LuaJTI/FFI and Python/CFFI (actually, the second was based on the first one). This API allows loading shared libraries (.DLL or .so), calling C functions and accessing C data structures, in pure PHP, without learning 3rd "intermediate" language.+It is proposed to extend PHP with a simple FFI API designed after LuaJTI/FFI and Python/CFFI (the latter was actually based on former). This API allows loading shared libraries (.DLL or .so), calling C functions and accessing C data structures, in pure PHP, without having to have deep knowledge in the Zend extension API, and without having to learn a 3rd "intermediate" language.
  
-The public API is implemented as a single class **FFI** with few static methods (some of them may be called non-statically), and overloaded object methods, that perform actual interaction with C data. Before diving into the details of FFI API, lets take a look into few examples, demonstrating simplicity of FFI API usage for regular tasks.+The public API is implemented as a single class **FFI** with a few static methods (some of them may be called non-statically), and overloaded object methods, that perform actual interaction with C data. Before diving into the details of FFI API, lets take a look into few examples, demonstrating simplicity of FFI API usage for regular tasks.
  
 ==== Calling a function from shared library ==== ==== Calling a function from shared library ====
Line 18: Line 18:
 <?php <?php
 // create FFI object, loading libc and exporting function printf() // create FFI object, loading libc and exporting function printf()
-$ffi = new FFI(+$ffi = FFI::cdef(
     "int printf(const char *format, ...);", // this is regular C declaration     "int printf(const char *format, ...);", // this is regular C declaration
     "libc.so.6");     "libc.so.6");
Line 29: Line 29:
 <?php <?php
 // create gettimeofday() binding // create gettimeofday() binding
-$ffi = new FFI("+$ffi = FFI::cdef("
     typedef unsigned int time_t;     typedef unsigned int time_t;
     typedef unsigned int suseconds_t;     typedef unsigned int suseconds_t;
Line 60: Line 60:
 <?php <?php
 // create FFI object, loading libc and exporting errno variable // create FFI object, loading libc and exporting errno variable
-$ffi = new FFI("int errno;", // this is regular C declaration+$ffi = FFI::cdef("int errno;", // this is regular C declaration
     "libc.so.6");     "libc.so.6");
 // print C errno // print C errno
Line 70: Line 70:
 <?php <?php
 // create C data structure // create C data structure
-$a = FFI::new("unsigned char[1024*1024]"); // "FFI::new" is different from "new FFI"+$a = FFI::new("unsigned char[1024*1024]");
 // work with it like with regular PHP array // work with it like with regular PHP array
 for ($i = 0; $i < count($a); $i++) { for ($i = 0; $i < count($a); $i++) {
Line 86: Line 86:
  
 ===== PHP FFI API ===== ===== PHP FFI API =====
-==== FFI::__construct([string $cdef = "" [, string $lib = null]]) ====+==== FFI::cdef([string $cdef = "" [, string $lib = null]]): FFI ====
  
 Creates a new FFI object. The first optional argument is a string, containing a sequence of declarations in regular C languages (types, structures, functions, variables, etc). Actually, this string may be copy-pasted from C header files. The second optional argument is a shared library file name, to be loaded and linked with definitions. All the declared entities are going to be available to PHP through overloaded functions or other FFI API functions: Creates a new FFI object. The first optional argument is a string, containing a sequence of declarations in regular C languages (types, structures, functions, variables, etc). Actually, this string may be copy-pasted from C header files. The second optional argument is a shared library file name, to be loaded and linked with definitions. All the declared entities are going to be available to PHP through overloaded functions or other FFI API functions:
Line 94: Line 94:
   * C type names may be used to create new C data structures using **FFI::new**, **FFI::type**, etc    * C type names may be used to create new C data structures using **FFI::new**, **FFI::type**, etc 
  
-Note: We don't support C preprocessor, yet. #include, #define and CPP macros don't work. +Note: At this time we don't support C preprocessor directives. #include, #define and CPP macros won't work. 
  
 ==== FFI::new(mixed $type [, bool $own = true [, bool $persistent = false]]): FFI\CData ==== ==== FFI::new(mixed $type [, bool $own = true [, bool $persistent = false]]): FFI\CData ====
Line 100: Line 100:
 Creates native data structure of given C type. $type may be any valid C string declaration or an instance of **FFI\CType** created before. Using the second argument, it's possible to create **owned** data (default), or unmanaged. In the first case, data structure is going to live together with returned FFI\CData object, and die when last reference is released by regular PHP reference counting or GC. However, in some cases, programmer may decide to keep C data even after, releasing of **FFI\CData** object and manually free it through **FFI::free()** similar to regular C. By default, the memory for the data is allocated on PHP request heap (using emalloc()), but it's also possible to use system heap, specifying true in the third argument. Creates native data structure of given C type. $type may be any valid C string declaration or an instance of **FFI\CType** created before. Using the second argument, it's possible to create **owned** data (default), or unmanaged. In the first case, data structure is going to live together with returned FFI\CData object, and die when last reference is released by regular PHP reference counting or GC. However, in some cases, programmer may decide to keep C data even after, releasing of **FFI\CData** object and manually free it through **FFI::free()** similar to regular C. By default, the memory for the data is allocated on PHP request heap (using emalloc()), but it's also possible to use system heap, specifying true in the third argument.
  
-This function may be called statically or as a method of previously created **FFI** object. In the first case, it may use only predefine C type names (e.g int, char, etc), and in the second, any type declared in the FFI object constructor.+This function may be called statically or as a method of previously created **FFI** object. In the first case, it may use only predefine C type names (e.g int, char, etc), and in the second, any type declared in the string passed to **FFI::cdef()** or file passed to **FFI::load()**.
  
 The returned **FFI\CData** object may be used in a number of ways as a regular PHP data The returned **FFI\CData** object may be used in a number of ways as a regular PHP data
Line 128: Line 128:
 Performs C type cast. It creates a new **FFI\CData** object, that references the same C data structure, but associated with different type. The resulting object doesn't own the C data, and the source $cdata must relive the result. C type may be specified as a string with any valid C type declaration or **FFI\CType** object, created before. Performs C type cast. It creates a new **FFI\CData** object, that references the same C data structure, but associated with different type. The resulting object doesn't own the C data, and the source $cdata must relive the result. C type may be specified as a string with any valid C type declaration or **FFI\CType** object, created before.
  
-This function may be called statically or as a method of previously created **FFI** object. In the first case, it may use only predefine C type names (e.g int, char, etc), and in the second, any type declared in the FFI object constructor.+This function may be called statically or as a method of previously created **FFI** object. In the first case, it may use only predefine C type names (e.g int, char, etc), and in the second, any type declared in the string passed to **FFI::cdef()** or file passed to **FFI::load()**..
  
 ==== FFI::addr(FFI\CData $cdata): FFI\CData ==== ==== FFI::addr(FFI\CData $cdata): FFI\CData ====
Line 138: Line 138:
 This function creates and returns a FFI\CType object for the given string containing C type declaration. This function creates and returns a FFI\CType object for the given string containing C type declaration.
  
-This function may be called statically or as a method of previously created **FFI** object. In the first case, it may use only predefine C type names (e.g int, char, etc), and in the second, any type declared in the FFI object constructor.+This function may be called statically or as a method of previously created **FFI** object. In the first case, it may use only predefine C type names (e.g int, char, etc), and in the second, any type declared in the string passed to **FFI::cdef()** or file passed to **FFI::load()**..
  
-==== FFI::array_type(FFI\CType $type, array $dims): FFI\CType ====+==== FFI::arrayType(FFI\CType $type, array $dims): FFI\CType ====
  
 Dynamically constructs a new C array type with elements of type defined by the first argument and dimensions specified by the second. In the following example $t1 and $t2 are equivalent array types. Dynamically constructs a new C array type with elements of type defined by the first argument and dimensions specified by the second. In the following example $t1 and $t2 are equivalent array types.
Line 146: Line 146:
 <code php> <code php>
 $t1 = FFI::type("int[2][3]"); $t1 = FFI::type("int[2][3]");
-$t2 = FFI::array_type(FFI::type("int"), [2, 3]);+$t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
 </code> </code>
  
Line 179: Line 179:
 ==== FFI::load(string $file_name): FFI ==== ==== FFI::load(string $file_name): FFI ====
  
-In addition to ability of embedding C declaration code into C constructor, it's also possible to load C declarations from separate C header file.+In addition to ability of embedding C declaration code into **FFI::cdef()**, it's also possible to load C declarations from separate C header file.
  
-Note: We don't support C preprocessor, yet. #include, #define and CPP macros don't work. +Note: C preprocessor directives are currently not supported. #include, #define and CPP macros don't work. 
  
 It's possible to specify shared libraries, that should be loaded, using special **FFI_LIB** define in the loaded C header file. It's possible to specify shared libraries, that should be loaded, using special **FFI_LIB** define in the loaded C header file.
  
-FFI definition parsing and shared library loading may take significant time. It's not useful to do it on each HTTP request in WEB environment. However, it's possible to pre-load FFI definitions and libraries at php startup, and instantiate FFI objects when necessary. Header files may be extended with special **FFI_SCOPE** define (default pre-loading scope is "C") and then loaded by **FFI::load()** during preloading. This leads to creation of persistent binding, that will be available to all the following requests through **FFI::scope()**.+FFI definition parsing and shared library loading may take significant time. It's not useful to do it on each HTTP request in a Web environment. However, it's possible to preload FFI definitions and libraries at PHP startup, and instantiate FFI objects when necessary. Header files may be extended with special **FFI_SCOPE** #define (e.g. #define FFI_SCOPE "foo", the default scope is "C") and then loaded by **FFI::load()** during preloading. This leads to creation of persistent binding, that will be available to all the following requests through **FFI::scope()**.  Please see the sample below for an example.
  
-It's possible to preload few C header files within the same scope.+It's possible to preload more than one C header file into the same scope.
  
 ==== FFI::scope(string $scope_name): FFI ==== ==== FFI::scope(string $scope_name): FFI ====
Line 198: Line 198:
  
 <code php> <code php>
-$zend = new FFI("+$zend = FFI::cdef("
  typedef int (*zend_write_func_t)(const char *str, size_t str_length);  typedef int (*zend_write_func_t)(const char *str, size_t str_length);
  extern zend_write_func_t zend_write;  extern zend_write_func_t zend_write;
Line 230: Line 230:
 ===== PHP FFI API Restriction ===== ===== PHP FFI API Restriction =====
  
-FFI API opens all the C power, and therefore enormous ability to make something wrong, crash PHP, or even worse. By default FFI API may be used only in CLI scripts and preloaded PHP files. This may be changed through **ffi.enable** INI directive.+FFI API opens all the C power, and consequently, also an enormous possibility to have something go wrong, crash PHP, or even worse. To minimize risk PHP FFI API usage may be restricted. By default FFI API may be used only in CLI scripts and preloaded PHP files. This may be changed through **ffi.enable** INI directive. This is INI_SYSTEM directive and it's value can't be changed at run-time.
  
   * **ffi.enable=false** completely disables PHP FFI API   * **ffi.enable=false** completely disables PHP FFI API
Line 288: Line 288:
 Accessing FFI data structures is significantly (about 2 times) slower, than accessing native PHP arrays and objects. It makes no sense to use them for speed, but may make sense to reduce memory consumption. This is true for all similar FFI implementations in interpretative mode. However, LuaJIT achieves improvement providing special support for FFI in its JIT. Accessing FFI data structures is significantly (about 2 times) slower, than accessing native PHP arrays and objects. It makes no sense to use them for speed, but may make sense to reduce memory consumption. This is true for all similar FFI implementations in interpretative mode. However, LuaJIT achieves improvement providing special support for FFI in its JIT.
  
-The following table shows time of execution of **ary3** benchmark from bench.php. +The following table shows time of execution of **ary3** benchmark from bench.php (in seconds, lower is better). 
  
 <code php> <code php>
Line 332: Line 332:
   ffi.enable=false|preload|true    ffi.enable=false|preload|true 
  
-allows enabling or disabling FFI API usage, or restricting it only to preloaded files. The default value is **preload**+allows enabling or disabling FFI API usage, or restricting it only to preloaded files. The default value is **preload**. This is INI_SYSTEM directive and it's value can't be changed at run-time.
  
 ===== Open Issues ===== ===== Open Issues =====
Line 344: Line 344:
   * Michael Wallner created [[https://github.com/m6w6/ext-psi|PHP System Interface]]   * Michael Wallner created [[https://github.com/m6w6/ext-psi|PHP System Interface]]
   * Sara Golemon thought, PHP needs something similar to [[https://github.com/facebook/hhvm/wiki/extension-api|HHVM HNI]]   * Sara Golemon thought, PHP needs something similar to [[https://github.com/facebook/hhvm/wiki/extension-api|HHVM HNI]]
 +
 +The usability of this FFI extension was proved by [[https://github.com/dstogov/php-tensorflow|TensorFlow binding]], implemented in pure PHP.
  
 ===== Future Scope ===== ===== Future Scope =====
-Currently, the performance of C data structures access is worst, then access of native PHP data structures (arrays and objects). This is a common problem of LuaJIT (in interpretator mode) and Python as well. However, LuaJIT may also compile these access code in very efficient way (almost as C compiler), and produce highly efficient machine code. It's planned to try similar things, implementing JIT for PHP.+Currently, the performance of C data structures access is worse than access of native PHP data structures (arrays and objects). This is a common problem, and both LuaJIT (in interpretator mode) and Python suffer from it as well. However, LuaJIT may also compile data access code in very efficient way (almost as C compiler), and produce highly efficient machine code. It's planned to try similar things, when we implement JIT for PHP.
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
-Include FFI extension into PHP-7.4+Include FFI extension into PHP-7.4 (bundle)
 This project requires 50%+1 majority This project requires 50%+1 majority
 +The voting started 2018-12-20 and will close on 2019-01-09
 +
 +<doodle title="Include FFI extension into PHP-7.4 (bundle)?" auth="user" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
Line 357: Line 365:
 ===== Implementation ===== ===== Implementation =====
 After the project is implemented, this section should contain  After the project is implemented, this section should contain 
-  - the version(s) it was merged into +  - it was merged into master (7.4) 
-  - a link to the git commit(s) +  - a link to the git [[https://github.com/php/php-src/commit/e089d506d5c7716c62cee5232d32ab22d0ddde26|commit]] 
-  - a link to the PHP manual entry for the feature +  - [[https://www.php.net/manual/en/book.ffi.php|PHP manual entry]] for the feature
-  - a link to the language specification section (if any)+
  
 ===== References ===== ===== References =====
Line 368: Line 375:
   - [[https://github.com/php/pecl-php-ffi|PECL FFI extension]]   - [[https://github.com/php/pecl-php-ffi|PECL FFI extension]]
   - [[https://github.com/facebook/hhvm/wiki/extension-api|HHVM HNI]]   - [[https://github.com/facebook/hhvm/wiki/extension-api|HHVM HNI]]
 +  - [[https://github.com/dstogov/php-tensorflow|TensoFlow PHP/FFI binding]]
  
 ===== Rejected Features ===== ===== Rejected Features =====
 Keep this updated with features that were discussed on the mail lists. Keep this updated with features that were discussed on the mail lists.
rfc/ffi.1543958399.txt.gz · Last modified: 2018/12/04 21:19 by dmitry

Page Tools