internals:extensions

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
Next revisionBoth sides next revision
internals:extensions [2013/04/10 12:06] – jpauliinternals:extensions [2013/04/10 13:47] – jpauli
Line 213: Line 213:
    Remember that there is no such thing like "dependencies" with Zend extensions. Only PHP extensions have a built-in dependency system with features we'll talk about later    Remember that there is no such thing like "dependencies" with Zend extensions. Only PHP extensions have a built-in dependency system with features we'll talk about later
        
 +Finally, the Zend extension is registered, it is then added to an exported global register storing Zend extensions pointers : ''zend_extensions (zend_llist type)''
  
 +==== Loading PHP extensions ====
 +After Zend extensions got registered, comes the PHP extensions turn. '' php_load_extension()'' does this job for each of them.
 +So, I repeat again : to register a new PHP extension, the engine calls for ''zend_register_module_ex(zend_module_entry *module)''.
 +This does few things :
 +  * Checks for extension dependencies, but only against conflicts, so **it does not load any other extension** than the one it's been called with
 +  * Checks if the extension has already been registered, if it is the case, warns
 +  * Registers the PHP extension functions into the global function table, calling ''zend_register_functions(module->functions)''
 +
 +   At this stage, the extensions order is not relevant. Extensions are simply registered, nothing more will happen here
 +
 +PHP extensions registration is quiet the same as Zend extensions registration : dlopen() the shared object, and checks for compatibility.
 +PHP extensions must export a ''get_module'' symbol. Note that this is different from Zend extensions. Zend extensions required that two symbols exist in the .so file, and those two symbols were structures. PHP extensions on their side only require one symbol to be declared, ''get_module'', and it will get casted as a function returning the ''zend_module_entry'' pointer.
 +
 +The ''get_module'' symbol is effectively exported when you compile your extension. Something like that in your extension main file :
 +<code c>
 +#define ZEND_GET_MODULE(name) \
 +    BEGIN_EXTERN_C()\
 + ZEND_DLEXPORT zend_module_entry *get_module(void) { return &name##_module_entry; }\
 +    END_EXTERN_C()
 +
 +#ifdef COMPILE_DL_FOO
 +ZEND_GET_MODULE(foo) 
 +#endif
 +</code>
 +
 +Then, the two fields ''zend_api'' and ''build_id'' from the freshly loaded ''zend_module_entry'' are checked against PHP internal API. Very similar to Zend extensions checks, except that at this stage, a PHP extension cannot check for other PHP extensions presence, like Zend extensions loading mechanism would allow. Dependency checking is done later, wait :-)
 +
 +After that, the loading mechanism fills in the ''module_number'' field from the PHP extension with just an integer that gets incremented by one at every PHP extension registration/load.
 +Now the PHP extension is going to be registered into a shared global variable, called ''module_registry'', beeing of type HashTable.
 +The registration step will perform two checks against the PHP extension beeing registered :
 +  * If the PHP extension is already present in the registry, warning then failure at registration
 +  * PHP extension dependencies **conflicts only** are checked
 +
 +The system checks for the eventually attached ''zend_module_deps'' to the ''zend_module_entry''. This structure basically allows a PHP extension to declare extensions it depends on, and dependencies have types :
 +  * A PHP extension can tell the system that it is not compatible with another already registered extension, so it will fail loading itself into the engine
 +  * A PHP extension can tell the system that it requires another PHP extension to be loaded before itself
 +
 +Here, **only conflicts are checked**, and as there is no particular registration order, a PHP extension A could declare beeing in conflict with B, but B could be loaded after A, hence the check wont work and you'll probably get some trouble.
 +When dealing with conflicts, it is better to sort the extensions in the php.ini file as a FIFO.
 +**PHP extensions will be registered in the exact same order they've been declared in php.ini**
 +
 +==== Activating PHP extensions ====
 +After registration, comes activation, and here is the step where the engine will effectively sort the PHP extensions in an order that make the dependencies be activated in a specific order.
 +   PHP extensions are activated before Zend extensions
 +
 +''zend_startup_modules()'' does the job of activating PHP extensions. It starts by sorting them in the ''module_registry'' Hashtable calling a sorting callback. This sort process will check for dependencies requirement, and sort the registry in a way that dependency requirements are activated first.
 +Then comes the "real" activation :  ''zend_startup_module_ex()'' is called on the freshly sorted module_registry.
 +It checks the extension field ''module_started'' , just a flag not to activate the same extension more than once. It then checks dependencies against requirements. If an extension requires another to be registered before itself and it's not the case, then an error will show up.
 +   Note that conflicts requirements have already been checked against, at extension loading (see last chapter)
 +After that, the extension globals are registered (call to ''globals_ctor()'' on the extension) and ''module_startup_func()'' is called on the extension, this is known as beeing the "MINIT process"
 +
 +==== Activating Zend extensions ====
 +   Zend extensions are then activated **after** PHP extensions
 +''zend_extension_startup()'' is called on the Zend extensions registry
 +   Remember that Zend extensions are never sorted in any way. You must then declare them in the FIFO order in php.ini. The engine wont touch your declaration order
 +''zend_extension_startup()'' just calls for the ''startup()'' function on Zend extensions, and appends a declaration message in the Zend phpinfo() message "With module XXX" showing to end user the Zend extension is both registered, and activated.
 +   Dont be fooled here, it's not the activate() function wich is triggered from Zend extensions, but the startup() function
 +
 +===== Extensions lifetime =====
 +You may know PHP's lifetime. Very basically, ''php_module_startup()'', then ''php_request_startup()'' at each request, followed by ''php_request_shutdown()'' , and then when PHP has to die : ''php_module_shutdown()''.
 +We already detailed php_module_startup() previously, to show how both PHP extensions and Zend extensions live into this stage.
 +
 +==== Request startup ====
 +Zend extensions come first, and their ''activate()'' function is called
 +PHP extensions come second, and their ''request_startup_func()'' is called, this is known as beeing the "RINIT" stage
 +
 +==== Request shutdown ====
 +PHP extensions come first, and their ''request_shutdown_func()'' is called, this is known as beeing the "RSHUTDOWN" stage
 +Zend extensions come after, and their ''deactivate()'' function is called
 +A third hook is called : ''post_deactivate_func()'', for each PHP extensions. PHP extensions are here given a chance to do some work after Zend extensions have all shut down
 +
 +==== PHP shutdown ====
 +PHP is ending, so as we are clean guys, we wrote code for PHP to clean up its environment in a right way and don't rely on the process terminating to destroy all the environment.
 +PHP extensions are first destroyed. This is done internally by relying on the Hashtable functionnalities. As the ''module_registry'' containing all the PHP extensions is a Hashtable, when it is constructed for the first time, a destructor is registered. This one is called here. It is ''module_destructor()''
 +It calls ''module_shutdown_func()'' on each extension, this is called the "MSHUTDOWN" stage. Then it destroys the extension globals calling ''globals_dtor()'' and finally it unregisters the PHP functions the extension may have registered at startup.
 +Finally, if the extension were to be loaded with ''dlopen()'' (not a statically compiled extension), it is then dlunload()'ed except if the env variable ZEND_DONT_UNLOAD_MODULES is used (usefull for debugging modules with valgrind, for example)
 +
 +After PHP extensions have all been shut down and unloaded, Zend extensions will be.
 +''zend_shutdown_extensions()'' is called, and its job is just to trigger ''shutdown()'' on each Zend extension (and destroy it from the main Zend extension registry)
 +
 +===== Main schema =====
internals/extensions.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools