1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297078 $ -->
<sect1 xml:id="internals2.structure.basics" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Basic constructs</title>
<simpara>
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.
</simpara>
<simpara>
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 pre-generated
<filename>php_counter.h</filename> and <filename>counter.c</filename> files
created by PHP 5.3's <command>ext_skel</command>, showing the pre-generated
declarations:
</simpara>
<note>
<simpara>
The astute reader will notice that there are several declarations in the
real files that aren't shown here. Those declarations are specific to
various Zend subsystems and are discussed elsewhere as appropriate.
</simpara>
</note>
<screen>
<![CDATA[
extern zend_module_entry counter_module_entry;
#define phpext_counter_ptr &counter_module_entry
#ifdef PHP_WIN32
# define PHP_COUNTER_API __declspec(dllexport)
#elif defined(__GNUC__) && __GNUC__ >= 4
# define PHP_COUNTER_API __attribute__ ((visibility("default")))
#else
# define PHP_COUNTER_API
#endif
#ifdef ZTS
#include "TSRM.h"
#endif
]]></screen>
<screen>
<![CDATA[
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
#include "php.h"
#include "php_ini.h"
#include "ext/standard/info.h"
#include "php_counter.h"
/* ... */
#ifdef COMPILE_DL_COUNTER
ZEND_GET_MODULE(counter)
#endif
]]></screen>
<itemizedlist>
<listitem>
<simpara>
The lines concerning <literal>counter_module_entry</literal> declare a
global variable, and a macroed pointer to it, which contains the
<literal>zend_module_entry</literal> 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.
</simpara>
</listitem>
<listitem>
<simpara>
<constant>PHP_COUNTER_API</constant> 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
<constant>PHPAPI</constant> macro is declared identically elsewhere and is
used by the standard extension to make the <function>phpinfo</function>
utility functions available to other extensions.
</simpara>
</listitem>
<listitem>
<simpara>
The include of <filename>TSRM.h</filename> is skipped if PHP, or the
extension, isn't being compiled with thread-safety, since in that case TSRM
isn't used.
</simpara>
</listitem>
<listitem>
<simpara>
A standard list of includes, especially the extension's own
<filename>php_counter.h</filename>, is given. <filename>config.h</filename>
gives the extension access to determinations made by
<command>configure</command>. <filename>php.h</filename> is the gateway to
the entire PHP and Zend APIs. <filename>php_ini.h</filename> adds the APIs
for runtime configuration (INI) entries. Not all extensions will use this.
Finally, <filename>ext/standard/info.h</filename> imports the
aforementioned <function>phpinfo</function> utility API.
</simpara>
</listitem>
<listitem>
<simpara>
<constant>COMPILE_DL_COUNTER</constant> will only be defined by
<command>configure</command> if the counter extension is both enabled and
wants to be built as a dynamically loadable module instead of being
statically linked into PHP. <constant>ZEND_GET_MODULE</constant> defines a
tiny function which Zend can use to get the extension's
<literal>zend_module_entry</literal> at runtime.
</simpara>
<note>
<simpara>
The astute reader who has peeked into
<filename>main/php_config.h</filename> after trying to build with the
counter module enabled statically may have noticed that there is also a
<constant>HAVE_COUNTER</constant> 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.
</simpara>
</note>
</listitem>
</itemizedlist>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
