diff --git a/internals2/structure/basics.xml b/internals2/structure/basics.xml new file mode 100644 index 0000000000..ccd5ca32d3 --- /dev/null +++ b/internals2/structure/basics.xml @@ -0,0 +1,154 @@ + + + + Basic constructs + + + C is a very low-level language by modern definitions. This means that it has + no built-in support for many features that PHP takes for granted, such as + reflection, dynamic module loading, bounds checking, threadsafe data + management and various useful data structures including linked lists and + hash tables. At the same time, C is a common denominator of language support + and functionality. Given enough work, none of these concepts are impossible; + the Zend Engine uses them all. + + + + A lot of effort has gone into making the Zend API both extensible and + understandable, but C forces certain necessary declarations upon any + extension that to an inexperienced eye seem redundant or plain unnecessary. + All of those constructs, detailed in this section, are "write once and + forget" in Zend Engine 2 and 3. Here are some excerpts from the pregenerated + php_counter.h and counter.c files + created by PHP 5.3's ext_skel, showing the pregenerated + declarations: + + + + + The astute reader will notice that there are several delcarations in the + real files that aren't shown here. Those declaractions are specific to + various Zend subsystems and are discussed elsewhere as appropriate. + + + + += 4 +# define PHP_COUNTER_API __attribute__ ((visibility("default"))) +#else +# define PHP_COUNTER_API +#endif + +#ifdef ZTS +#include "TSRM.h" +#endif +]]> + + + + + + + The lines concerning counter_module_entry declare a + global variable, and a macroed pointer to it, which contains the + zend_module_entry for the extension. Despite the later + discussion regarding the drawbacks of "true" globals, this usage is + intentional; Zend takes precautions to avoid misusing this variable. + + + + + PHP_COUNTER_API is declared for use by non-PHP + functions the module intends to export for the use of other modules. The + counter extension doesn't declare any of these, and in the final version of + the header file, this macro has been removed. The + PHPAPI macro is declared identically elsewhere and is + used by the standard extension to make the phpinfo + utility functions available to other extensions. + + + + + The include of TSRM.h is skipped if PHP, or the + extension, isn't being compiled with thread-safety, since in that case TSRM + isn't used. + + + + + A standard list of includes, especially the extension's own + php_counter.h, is given. config.h + gives the extension access to determinations made by + configure. php.h is the gateway to + the entire PHP and Zend APIs. php_ini.h adds the APIs + for runtime configuration (INI) entries. Not all extensions will use this. + Finally, ext/standard/info.h imports the + aforementioned phpinfo utility API. + + + + + COMPILE_DL_COUNTER will only be defined by + configure if the counter extension is both enabled and + wants to be built as a dynamically loadable module instead of being + statically linked into PHP. ZEND_GET_MODULE defines a + tiny function which Zend can use to get the extension's + zend_module_entry at runtime. + + + + The astute reader who has peeked into + main/php_config.h after trying to build with the + counter module enabled statically may have noticed that there is also a + HAVE_COUNTER constant defined that the source code + doesn't check for. There's a simple reason this check isn't done: It's + unnecessary. If the extension isn't enabled, the source file will never be + compiled. + + + + + + + + diff --git a/internals2/structure/globals.xml b/internals2/structure/globals.xml index 5e7af9bcec..798b5d0b81 100644 --- a/internals2/structure/globals.xml +++ b/internals2/structure/globals.xml @@ -1,5 +1,5 @@ - + Extension globals @@ -69,6 +69,44 @@ PHP_FUNCTION(counter_get) + + Declaring module globals + + + Whether a module uses only a single global or dozens, they must be defined + in a structure, and that structure must be declared. There are some macros + that assist with doing so in a way that avoids name conflicts between + modules: ZEND_BEGIN_MODULE_GLOBALS, + ZEND_END_MODULE_GLOBALS, and + ZEND_DECLARE_MODULE_GLOBALS. All three take as a + parameter the short name of the module, which in the case of the counter + module is simply "counter". Here is the global structure + declaration from php_counter.h: + + + The counter module's globals + + + + + + And this is the declaration from counter.c: + + + The counter module's global structure declaration + + + + + + + + Extension structure @@ -14,6 +14,7 @@ &internals2.structure.files; + &internals2.structure.basics; &internals2.structure.modstruct; &internals2.structure.globals; &internals2.structure.lifecycle;