From abfe11a93454251be192bfde59be4ed05bc099fe Mon Sep 17 00:00:00 2001
From: Gwynne Raskind <gwynne@php.net>
Date: Mon, 20 Oct 2008 23:10:53 +0000
Subject: [PATCH] A bit more on globals, and beginnings of a module lifecycle

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@267581 c90b9560-bf6c-de11-be94-00142212c4b1
---
 internals2/intro.xml               |  4 +-
 internals2/structure/globals.xml   | 40 +++++++++++++++++-
 internals2/structure/lifecycle.xml | 66 +++++++++++++++++++++++++++++-
 3 files changed, 106 insertions(+), 4 deletions(-)

diff --git a/internals2/intro.xml b/internals2/intro.xml
index e56b936249..0b220c77af 100644
--- a/internals2/intro.xml
+++ b/internals2/intro.xml
@@ -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
diff --git a/internals2/structure/globals.xml b/internals2/structure/globals.xml
index f4b55742a2..02c45a7d7c 100644
--- a/internals2/structure/globals.xml
+++ b/internals2/structure/globals.xml
@@ -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 @@ ZEND_DECLARE_MODULE_GLOBALS(counter)
      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>
 
diff --git a/internals2/structure/lifecycle.xml b/internals2/structure/lifecycle.xml
index c7499f3b6a..8ecdc19c0c 100644
--- a/internals2/structure/lifecycle.xml
+++ b/internals2/structure/lifecycle.xml
@@ -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