additions and fixes

Author: Julien Pauli

Book/index.rst

@@ -39,6 +39,8 @@ This part concerns only the PHP 7 branch. It is under development.
     php7/extensions_design.rst
     php7/memory_management.rst
     php7/zend_engine.rst
+    php7/debugging.rst
+
 ..
     php7/hashtables.rst
     php7/classes_objects.rst

Book/php7/debugging.rst

@@ -0,0 +1,8 @@
+Debugging with GDB
+==================
+
+This chapter will introduce you with the GNU C debugger, aka GDB. When a crash happens, you usually have to find the 
+guilty part in thousands of lines. You need tools for that, and GDB is the most commonly used debugger under Unix 
+platforms. Here we'll give you an introduction to GDB and how to practice with it against the PHP source code.
+
+

Book/php7/extensions_design/php_functions.rst

@@ -85,7 +85,7 @@ You'll pass to the function vector a declared vector of functions. Let's see tog
     static const zend_function_entry pib_functions[] =
     {
         PHP_FE(fahrenheit_to_celsius, NULL)
-    }
+    };
 
     zend_module_entry pib_module_entry = {
         STANDARD_MODULE_HEADER,
@@ -175,7 +175,7 @@ Fortunately, you are once more provided some macros to abstract the hard job for
 
     ZEND_BEGIN_ARG_INFO_EX(arginfo_fahrenheit_to_celsius, 0, 0, 1)
         ZEND_ARG_INFO(0, fahrenheit)
-    ZEND_END_ARG_INFO();
+    ZEND_END_ARG_INFO()
 
 The code above details how to create an argument, but when we expand macros, we can feel some difficulty::
 

Book/php7/extensions_design/php_lifecycle.rst

@@ -157,9 +157,10 @@ A request just showed in, and PHP is about to treat it here. In ``RINIT()``, you
 treat that precise request. PHP is a share-nothing architecture, and as-is, it provides 
 :doc:`memory management <../memory_management>` facilities.
 
-In ``RINIT()``, if you need to allocate dynamic memory, you'll use Zend Memory Manager. You will call for ``emalloc()``.
-Zend Memory Manager tracks the memory you allocate through it, and when the request shuts down, it will attempt to free 
-the request-bound memory if you forgot to do so (you should not).
+In ``RINIT()``, if you need to allocate dynamic memory, you'll use 
+:doc:`Zend Memory Manager <../memory_management/zend_memory_manager>`. You will call for ``emalloc()``.
+:doc:`Zend Memory Manager <../memory_management/zend_memory_manager>` tracks the memory you allocate through it, and 
+when the request shuts down, it will attempt to free the request-bound memory if you forgot to do so (you should not).
 
 You should not require persistent dynamic memory here, aka libc's ``malloc()`` or Zend's ``pemalloc()``. If you require 
 persistent memory here, and forgets to free it, you'll create leaks that will stack as PHP treats more and more 
@@ -265,19 +266,20 @@ Thoughts on PHP lifecycle
 
 As you may have spotted, ``RINIT()`` and ``RSHUTDOWN()`` are especially crucial as they could get triggered thousands 
 of times on your extension. If the PHP setup is about Web (not CLI), and has been configured so that it can treat an 
-infinite number of requests, thus your RINIT()/RSHUTDOWN() couple will be called an infinite amount of time.
+infinite number of requests, thus your ``RINIT()/RSHUTDOWN()`` couple will be called an infinite amount of time.
 
 We'd like to once more get your attention about memory management. The little tiny byte you'll eventually leak while 
 treating a request (between ``RINIT()`` and ``RSHUTDOWN()``) will have dramatic consequences on fully loaded servers.
+That's why you are advised to use :doc:`Zend Memory Manager <../memory_management/zend_memory_manager>` for such 
+allocations. PHP will forget and free the request memory at the end of every request as part of the share-nothing 
+architecture, that's PHP's internal design.
 
 Also, if you crash with a SIGSEGV signal (bad memory access), you crash the entire process. If the PHP setup was using 
 threads as multi-processing engine, then you crash every other thread with you, and could even crash the webserver.
 
 .. note:: The C language is not the PHP language. Using C, errors and mistakes in your program will highly probably 
           lead to a program crash and termination.
 
-.. todo: Add a chapter about debugging. Add a chapter about memory leak tracking.
-
 Hooking by overwritting function pointers
 *****************************************
 

Book/php7/internal_types/zend_resources.rst

@@ -3,7 +3,7 @@ The Resource type: zend_resource
 
 Even though PHP could really get rid of the "resource" type, because 
 :doc:`custom object storage <./classes_objects/custom_object_storage>` allows to build a PHP representation of any 
-abstract kind of data, that resource type still exists in PHP, and you may need to deal with it.
+abstract kind of data, that resource type still exists in the current version of PHP, and you may need to deal with it.
 
 If you need to create resources, we really would like to push you not to, but instead use objects and their 
 :doc:`custom storage <./classes_objects/custom_object_storage>` management. Objects is the PHP type that can embed 
@@ -41,7 +41,7 @@ The ``type`` is used to regroup resources of the same type together. This is abo
 how they are fetched back from their handle.
 
 Finally, the ``ptr`` field in ``zend_resource`` is your abstract data. Remember resources are about storing an abstract 
-data that cannot fit in any data type PHP can represent natively.
+data that cannot fit in any data type PHP can represent natively (but objects could, like we said earlier).
 
 Resource types and resource destruction
 ---------------------------------------
@@ -61,12 +61,13 @@ Destructors are grouped by types, so are resources themselves. You won't apply t
 There also exists two kinds of resources, here again differenciated about their lifetime.
 
 * Classical resources, the most used ones, do not persist across several requests, their destructor is called at 
-  request shutdown
+  request shutdown.
 * Persistent resources will persist across several requests and will only get destroyed when the PHP process dies.
 
 .. note:: You may be interested by :doc:`the PHP lifecycle <../extensions_design/php_lifecycle>` chapter that shows you 
-          the different steps occuring in PHP's process life.
-
+          the different steps occuring in PHP's process life. Also, the 
+          :doc:`Zend Memory Manager chapter <../memory_management/zend_memory_manager>` may help in understanding 
+          concepts of persistent and request-bound memory allocations.
 
 Playing with resources
 ----------------------
@@ -145,6 +146,10 @@ connection") into the same resource table. Resource types have names, so that th
 debug statement (like a ``var_dump($my_resource)``), and they also are represented as an integer used internaly to 
 fetch back the resource pointer from it, and to register a destructor with the resource type.
 
+.. note:: Like you can see, if we would have used objects, those represent types by themselves, and there would'nt have 
+          to happen that step of fetching back a resource from its identifier verifying its type. Objects are 
+          self-describing types. But resources are still a valid data type for the current PHP version.
+
 Reference counting resources
 ----------------------------
 

Book/php7/memory_management/memory_debugging.rst

@@ -367,13 +367,10 @@ Finally here is a last example to show a use-after-free scenario. This is also a
 which is as bad as bad-memory-access: it creates security flaws that can lead to very nasty behaviors.
 Obviously, valgrind can detect use-after-free. Here is one::
 
-    PHP_MINIT_FUNCTION(pib)
-    {
-	char *foo = strdup("foo");
-	free(foo);
+    char *foo = strdup("foo");
+    free(foo);
 
-	memcpy(foo, "foo", sizeof("foo"));
-    }
+    memcpy(foo, "foo", sizeof("foo"));
 
 Here again, a PHP scenario that has nothing to do with PHP but still. We free a pointer, and reuse it after. This is a 
 big mistake. Let's ask valgrind::