internals:engine

Differences

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

Link to this comparison view

internals:engine [2012/03/07 00:30]
cataphract [Extension Globals]
internals:engine [2017/09/22 13:28]
Line 1: Line 1:
-This page contains bits and pieces of the Zend Engine documentation:​ 
  
-===== Op-array structure ===== 
- 
-  * each op_array has an array of literals (constant values) 
-  * opocde operands don't contain zval directly any more but points to thistable instead 
-  * during compilation they are accessible by index e.g: <​code>​op_array->​literals[opline->​op1.constant].constant</​code>​ 
-  * the pass_two() changes indexes into pointers so during execution they are accessible by: <​code>​opline->​op1.zv</​code>​ 
- 
-===== Objects ===== 
-See [[internals:​engine:​objects|here]]. 
- 
-===== FAQ ===== 
-These are questions, often times with answers, for the PHP Internals. This document is temporary until it's polished and finds a home within the PHP Manual sources. Feel free to add questions with or without answers. 
- 
-Note: This is rough, feel free to clean it up. 
- 
-==== C++ ==== 
-Extensions can be written in C++, you have to add PHP_REQUIRE_CXX to the config.m4 file to make the build system C++-aware though. 
- 
-To allow static builds of the extension one has to mind this: 
- 
-  09:20:43 <​johannes_>​ and ext/​extname/​php_extname.h has to be a valid C header, not C++, as it's included in internal_functions.c ... 
-  09:22:06 <​dsp_>​ hmm, that's the point.. 
-  09:23:01 <​johannes_>​ you can have your own additional header for C++ suff, but that one has to be C compatible 
- 
- 
-==== Memory Management ==== 
- 
-  [12:00pm] scoates: ok.. last question for now, I think: should I explicitly destroy on RSHUTDOWN, or let the non-persistent flag take care of that? 
-  [12:00pm] johannes_: always cleanup yourself 
- 
-Note here: while MM shutdown will take care of all allocated memory, it won't run any dtors etc., that's why it is important to clean up the resources properly - otherwise external dependencies can be messed up. And of course you'd get leaks reported in the debug mode.  
- 
-==== Causes for crashes ==== 
- 
-=== Throwing Exceptions === 
- 
-If throwing exceptions results in a segmentation fault on 64bit systems only, then be sure that you have: 
-  #include "​zend_exceptions.h" ​ 
- 
-(Remark: This header is always needed. The segfault might be caused by the fact, that C defaults the return value and parameters of undefined parameters to int. In cases where pointers and/or long data types are needed this might be wrong so a wrong function call is being made. A good compiler should give a warning. --johannes) 
- 
-==== Hashes ==== 
-  [11:58am] scoates: what's the difference between zend_hash_[add] and zend_hash_quick_[add] ? 
-  [11:58am] scoates: removal of gofaster loops? (-: 
-  [11:58am] Derick: with the 2nd one you can provide an already calculated hash-list index 
- 
-  [11:59am] scoates: and the hashtable will automatically grow on _add, right? the length passed to init is just a hint? 
-  [11:59am] johannes_: right 
-===== Unsorted ===== 
- 
-Add your random stuff here. I'll move it/update it/fix it (Derick) 
- 
-How to get %%__LINE__ and __FILE__%%? 
-  * zend_get_executed_filename() and zend_get_executed_lineno() 
- 
-How do I detect the SAPI? 
-  * The fastest way [to detect CLI] would be: if (sapi_module.phpinfo_as_text) { ... } 
-  * sapi_module is a true global, not a TSRM protected one 
-  * sapi_module.name and sapi_module.pretty_name contain the name as char* 
-  * sapi_module.phpinfo_as_text is a flag which can be set by different SAPIs to request text only phpinfo() output, currently only CLI and embed do that afaik, CGI does not. 
- 
- 
-==== Extension Globals ===== 
- 
-To use extension globals (which are either true globals or thread local globals, depending on whether ZTS is enabled), follow these steps: 
- 
-- In php_extname.h,​ declare which global variables you need with: 
- 
-<​code>​ 
-ZEND_BEGIN_MODULE_GLOBALS(extname) 
- int var1; 
- char *var2;​ 
- .... 
-ZEND_END_MODULE_GLOBALS(extname) 
-</​code> ​ 
- 
-This will declare a structure (typedef'​d to zend_extname_globals) that will hold all your globals. 
- 
-- In php_extname.h,​ add <​code>​ZEND_EXTERN_MODULE_GLOBALS(extname);</​code>​. This will produce an allusion that will allow you to access the globals from every compile unit that includes php_extname.h In particular, this produces an allusion to an integer named extname_globals_id in ZTS builds or directly to a zend_extname_globals named extname_globals in non-ZTS builds. 
- 
-- In php_extname.h,​ define a macro named EXTNAME_G, like this: 
-<​code>​ 
-#ifdef ZTS 
-# define EXTNAME_G(v) TSRMG(extname_globals_id,​ zend_extname_globals *, v) 
-#else 
-# define EXTNAME_G(v) (extname_globals.v) 
-#endif 
-</​code>​ 
- 
-This will allow you to access the globals in a consistent manner in both ZTS and non-ZTS builds, like this: 
- 
-<​code>​EXTNAME_G(var1)</​code>​ 
- 
-- Now that you have declared the type that aggregates the globals and the variable that holds the globals, you must define the globals. In extname.c, add 
- 
-<​code>​ZEND_DECLARE_MODULE_GLOBALS(extname);</​code>​ 
- 
-This produces a tentative definition of extname_globals_id or extname_globals (depending on whether it's a ZTS or non-ZTS build). 
- 
-- If you needn'​t do any startup operations on your variables, you would already have function extension globals in non-ZTS builds. Tipically, you will also want to initialize some extension globals (for instance, to allocate some memory for the var2 extension global above) -- this is done with globals constructors and destructors. To make it work in ZTS builds and allow such operations, add the following to your zend_module_entry:​ 
- 
-<​code>​ 
-zend_module_entry extname_module_entry = { 
- ... 
- ZEND_MODULE_INFO_N(extname),​ 
- PHP_EXTNAME_VERSION,​ 
- ZEND_MODULE_GLOBALS(extname),​ 
- ZEND_MODULE_GLOBALS_CTOR_N(extname),​ //may be NULL 
- ZEND_MODULE_GLOBALS_DTOR_N(extname),​ //may be NULL 
- ... 
-} 
-</​code>​ 
- 
-Note: do not use ZEND_INIT_MODULE_GLOBALS/​ts_allocate_id. If used a shared extension, they will provoke an attempt to call the destructor after the module has been unloaded! Also, for all that is holy, do NOT initialize globals on MINIT (<​code>​EXTNAME_G(var_ptr)</​code>​ = NULL), that won't work correctly in ZTS as it won't initialize the value in all threads. 
- 
-- Now define the constructor and destructor functions: 
- 
-<​code>​ 
-ZEND_MODULE_GLOBALS_CTOR_D(extname) 
-{ 
- extname_globals->​arg2 = pemalloc(1024,​ 1); 
-} 
- 
-ZEND_MODULE_GLOBALS_DTOR_D(extname) 
-{ 
- pefree(extname_globals->​arg2,​ 1); 
-} 
-</​code>​ 
- 
-The globals constructor and destructor are NOT execute per-request,​ they are part of the module startup/​shutdown. The globals can store data across requests. If you need to do per-request operations to the globals, use module-activate and module-deactivate callbacks. 
- 
-Note: ZEND_MODULE_GLOBALS_CTOR_D will declare a function as receiving a zend_extname_globals*,​ not void* and zend_module_entry is supposed to contain a function pointer type that receives void*. I think this violates the C standard (the declarations are incompatible),​ but should however by safe since the arguments have the same size. 
internals/engine.txt · Last modified: 2017/09/22 13:28 (external edit)