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
155
156
157
158
159
160
161
162
163
164
165
166
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 330056 $ -->
<sect1 xml:id="internals2.memory.tsrm" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Thread-Safe Resource Manager</title>
<simpara>
When PHP is built with Thread Safety enabled, the engine requires a way to isolate contexts from one another, such that the threads of a process may service individual requests without interference. TSRM is omnipitent within PHP, extension authors have to do very little in order to make sure their extensions can function in both a Thread Safe and Non Thread Safe architecture.
</simpara>
<example xml:id="internals2.structure.globals.using.accessor2">
<title>Accessor macros for per-module globals</title>
<programlisting role="c">
<![CDATA[
#ifdef ZTS
#define COUNTER_G(v) TSRMG(counter_globals_id, zend_counter_globals *, v)
#else
#define COUNTER_G(v) (counter_globals.v)
#endif
]]>
</programlisting>
</example>
<simpara>
The snippet above shows how an extension author is expected to define their global accessors. The TSRMG macro takes an identifier, type cast and element name. The identifier is assigned by TSRM during initialization of the module. Declaring global accessors in this way ensures that an extension can operate safely in a Thread Safe and Non Thread Safe architecture using the same logic.
</simpara>
<simpara>
TSRM manages the isolation and safety of all global structures within PHP, from executor globals to extension globals, a pointer to the isolated storage is also passed around with most, or many of the API functions. The macros TSRMLS_C and TSRMLS_CC translate to "thread safe local storage" and "thread safe local storage prefixed with a comma" respectively.
</simpara>
<simpara>
If a function requires a pointer to TSRM, it is declared with the macro TSRMLS_D or TSRMLS_DC in it's prototype, wihch translates to "thread safe local storage only" and "thread safe local storage prefixed with a comma" respectively. Many macros within the engine reference TSRM, so it is a good idea to declare most things to accept TSRM, such that if they need to call upon TSRM they do not have to fetch a pointer during execution.
</simpara>
<simpara>
Because TSRM is thread local, and some functions (for compatibility reasons) are not able to accept TSRM directly, the macro TSRMLS_FETCH exists, which requests that TSRM fetches the pointer to the thread local storage. This should be avoided wherever it can be, as it is not without cost in a Thread Safe setup.
</simpara>
<note>
<simpara>
While developing extensions, build errors that contain "tsrm_ls is undefined" or errors to that effect stem from the fact that TSRMLS is undefined in the current scope, to fix this, declare the function to accept TSRMLS with the appropriate macro, if the prototype of the function in question cannot be changed, you must call TSRMLS_FETCH within the function body.
</simpara>
</note>
<simpara>
The functionality documented hereafter is aimed at advanced use of TSRM. It is not ordinary for extensions to have to interact with TSRM directly, the pecl programmer should use API's above TSRM such as the Module Globals API.
</simpara>
<table xml:id="internals2.memory.tsrm.iapis">
<title>TSRM Internals</title>
<tgroup cols="2">
<thead>
<row>
<entry>Prototype</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>typedef int ts_rsrc_id</code></entry>
<entry>The type definition to represent a resource by numeric identifiers</entry>
</row>
<row>
<entry><code>int tsrm_startup(int expected_threads, int expected_resources, int debug_level, char *debug_filename)</code></entry>
<entry><code>expected_threads</code> and <code>expected_resources</code> are not hard limits. <code>debug_level</code> and <code>debug_filename</code> only have an effect on windows in Debug mode or when TSRM_DEBUG is defined. Called once per process in ZTS mode during server startup.</entry>
</row>
<row>
<entry><code>void tsrm_shutdown(void)</code></entry>
<entry>
Should be the last thing called in the process to destroy and free all storage TSRM storage in ZTS mode.
</entry>
</row>
<row>
<entry><code>ts_rsrc_id ts_allocate_id(ts_rsrc_id *rsrc_id, size_t size, ts_allocate_ctor ctor, ts_allocate_dtor dtor)</code></entry>
<entry>
Allocates and thread safe pointer of <code>size</code> bytes, calling <code>ctor</code> on the pointer, assigning (and returning) the id to <code>rsrc_id</code>, the <code>dtor</code> is called when the resource is free'd. Module globals are isolated in ZTS mode using this API.
</entry>
</row>
<row>
<entry><code>void *ts_resource_ex(ts_rsrc_id id, THREAD_T *th_id)</code></entry>
<entry>
Fetches a resource by previously allocated <code>id</code> from the entries created by the specified thread identifed by <code>th_id</code>.
</entry>
</row>
<row>
<entry>
<code>void *ts_resource(ts_rsrc_id id)</code>
</entry>
<entry>
Fetches a resource by previously allocated <code>id</code> from the entries created by the calling thread.
</entry>
</row>
<row>
<entry><code>void ts_free_thread(void)</code></entry>
<entry>
Destroys and frees the entries for the calling thread, currently this API is only used by ISAPI module.
</entry>
</row>
<row>
<entry>
<code>void ts_free_id(ts_rsrc_id id)</code>
</entry>
<entry>
Destroys the resource identified by previously allocated <code>id</code>. Module globals are cleaned up in ZTS mode using this API.
</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<simpara>There are more TSRM API functions to enable the creation and destruction of interpreter contexts, the usage of such functionality is out of the scope of this documentation, please see TSRM/TSRM.h for more information.</simpara>
</note>
<table xml:id="internals2.memory.tsrm.mapis">
<title>TSRM Mutex API</title>
<tgroup cols="2">
<thead>
<row>
<entry>Prototype</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>MUTEX_T tsrm_mutex_alloc(void)</code></entry>
<entry>Allocates and returns a suitable MUTEX_T for the environment.</entry>
</row>
<row>
<entry><code>int tsrm_mutex_lock(MUTEX_T mutexp)</code></entry>
<entry>
Locks <code>mutexp</code> for the calling thread.
</entry>
</row>
<row>
<entry><code>int tsrm_mutex_unlock(MUTEX_T mutexp)</code></entry>
<entry>
Unlocks <code>mutexp</code> for the calling thread.
</entry>
</row>
<row>
<entry><code>void tsrm_mutex_free(MUTEX_T mutexp);</code></entry>
<entry>
Destroys and frees the (unlocked) and previously allocated <code>mutexp</code>.
</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<simpara>The mutex API is exposed by TSRM. However, its internal usage is far too wide to document usefully here, none the less, basic functionality and prototypes are documented here.</simpara>
</note>
</sect1>
|
