cvs: phpdoc /en/internals2 intro.xml /en/internals2/structure globals.xml lifecycle.xml

gwynne Mon Oct 20 23:10:53 2008 UTC Modified files: /phpdoc/en/internals2 intro.xml /phpdoc/en/internals2/structure globals.xml lifecycle.xml Log: A bit more on globals, and beginnings of a module lifecycle http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/intro.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/internals2/intro.xml diff -u phpdoc/en/internals2/intro.xml:1.5 phpdoc/en/internals2/intro.xml:1.6 --- phpdoc/en/internals2/intro.xml:1.5 Wed Apr 9 07:00:27 2008 +++ phpdoc/en/internals2/intro.xml Mon Oct 20 23:10:53 2008 @@ -1,7 +1,9 @@ <?xml version="1.0" encoding="ISO-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <!-- + &internals2.intro; + &internals2.counter; &internals2.buildsys.index; configure options, ext_skel, config.m4, config.w32, static vs. dynamic builds &internals2.structure.index; ext_skel, module structure, globals, lifecycle, tests &internals2.memory.index; management, persistence, TSRM http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/globals.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/internals2/structure/globals.xml diff -u phpdoc/en/internals2/structure/globals.xml:1.4 phpdoc/en/internals2/structure/globals.xml:1.5 --- phpdoc/en/internals2/structure/globals.xml:1.4 Fri Jun 6 10:07:37 2008 +++ phpdoc/en/internals2/structure/globals.xml Mon Oct 20 23:10:53 2008 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <sect1 xml:id="internals2.structure.globals" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Extension globals</title> @@ -174,6 +174,44 @@ more information. </simpara> </warning> + + <simpara> + So with all of that in mind, here is our new version of the + <function>counter_get</function>: + </simpara> + + <example xml:id="internals2.structure.globals.intro.right-way"> + <title>The right way to store the basic counter interface's value</title> + <programlisting role="c"> +<![CDATA[ +/* php_counter.h */ +ZEND_BEGIN_MODULE_GLOBALS(counter) + long basic_counter_value; +ZEND_END_MODULE_GLOBALS(counter) + +#ifdef ZTS +#define COUNTER_G(v) TSRMG(counter_globals_id, zend_counter_globals *, v) +#else +#define COUNTER_G(v) (counter_globals.v) +#endif + +/* counter.c */ +ZEND_DECLARE_MODULE_GLOBALS(counter) + +/* ... */ + +PHP_FUNCTION(counter_get) +{ + RETURN_LONG(COUNTER_G(basic_counter_value)); +} +]]> + </programlisting> + </example> + + <simpara> + This is a correct implementation. It is not, however, a complete one. The + section <xref linkend="internals2.structure.lifecycle"/> explains why. + </simpara> </sect2> http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/lifecycle.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/internals2/structure/lifecycle.xml diff -u phpdoc/en/internals2/structure/lifecycle.xml:1.1 phpdoc/en/internals2/structure/lifecycle.xml:1.2 --- phpdoc/en/internals2/structure/lifecycle.xml:1.1 Thu Jun 21 00:30:22 2007 +++ phpdoc/en/internals2/structure/lifecycle.xml Mon Oct 20 23:10:53 2008 @@ -1,8 +1,70 @@ <?xml version="1.0" encoding="ISO-8859-1" ?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <sect1 xml:id="internals2.structure.lifecycle" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Life cycle of an extension</title> - <para/> + + <simpara> + A Zend extension goes through several phases during its lifetime. All of + these phases are opportunities for the developer to perform various + initialization, termination, or informational functions. The Zend API allows + for hooks into five separate phases of an extension's existence, apart from + calls by PHP functions. + </simpara> + + <sect2 xml:id="internals2.structure.lifecycle.mod-vs-req"> + <title>Loading, unloading, and requests</title> + + <simpara> + As the Zend engine runs, it processes one or more "requests" from its + client. In the traditional CGI implementation, this corresponds to one + execution of a process. However, many other implementations, most notably + the Apache module, can map many requests onto a single PHP process. A Zend + extension may thus see many requests in its lifetime. + </simpara> + </sect2> + + <sect2 xml:id="internals2.structure.lifecycle.overview"> + <title>Overview</title> + + <itemizedlist> + <listitem> + <simpara> + In the Zend API, a module is loaded into memory only once when the + associated PHP process starts up. Each module recieves a call to the + "module initialization" function specified in its + <constant>zend_module</constant> structure as it is loaded. + </simpara> + </listitem> + + <listitem> + <simpara> + Whenever the associated PHP process starts to handle a request from its + client - i.e. whenever the PHP interpreter is told to start working - each + module receives a call to the "request initialization" function specified + in its <constant>zend_module</constant> structure. + </simpara> + </listitem> + + <listitem> + <simpara> + Whenever the associated PHP process is done handling a request, each + module receives a call to the "request termination" function specified in + its <constant>zend_module</constant> structure. + </simpara> + </listitem> + + <listitem> + <simpara> + A given module is unloaded from memory when its associated PHP process is + shut down in an orderly manner. The module receives a call to the "module + termination" function specified in its + <constant>zend_module</constant> structure at this time. + </simpara> + </listitem> + </itemizedlist> + + </sect2> + </sect1> <!-- Keep this comment at the end of the file