<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Thread-Safe Resource Manager</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="internals2.memory.persistence.html">Data persistence</a></div>
<div class="next" style="text-align: right; float: right;"><a href="internals2.variables.html">Working with Variables</a></div>
<div class="up"><a href="internals2.memory.html">Memory management</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="internals2.memory.tsrm" class="sect1">
<h2 class="title">Thread-Safe Resource Manager</h2>
<p class="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.
</p>
<div class="example" id="internals2.structure.globals.using.accessor2">
<p><strong>Example #1 Accessor macros for per-module globals</strong></p>
<div class="example-contents">
<div class="ccode"><pre class="ccode">#ifdef ZTS
#define COUNTER_G(v) TSRMG(counter_globals_id, zend_counter_globals *, v)
#else
#define COUNTER_G(v) (counter_globals.v)
#endif</pre>
</div>
</div>
</div>
<p class="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.
</p>
<p class="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.
</p>
<p class="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.
</p>
<p class="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.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="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.
</span>
</p></blockquote>
<p class="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.
</p>
<table id="internals2.memory.tsrm.iapis" class="doctable table">
<caption><strong>TSRM Internals</strong></caption>
<thead>
<tr>
<th>Prototype</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><code class="code">typedef int ts_rsrc_id</code></td>
<td>The type definition to represent a resource by numeric identifiers</td>
</tr>
<tr>
<td><code class="code">int tsrm_startup(int expected_threads, int expected_resources, int debug_level, char *debug_filename)</code></td>
<td><code class="code">expected_threads</code> and <code class="code">expected_resources</code> are not hard limits. <code class="code">debug_level</code> and <code class="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.</td>
</tr>
<tr>
<td><code class="code">void tsrm_shutdown(void)</code></td>
<td>
Should be the last thing called in the process to destroy and free all storage TSRM storage in ZTS mode.
</td>
</tr>
<tr>
<td><code class="code">ts_rsrc_id ts_allocate_id(ts_rsrc_id *rsrc_id, size_t size, ts_allocate_ctor ctor, ts_allocate_dtor dtor)</code></td>
<td>
Allocates and thread safe pointer of <code class="code">size</code> bytes, calling <code class="code">ctor</code> on the pointer, assigning (and returning) the id to <code class="code">rsrc_id</code>, the <code class="code">dtor</code> is called when the resource is free'd. Module globals are isolated in ZTS mode using this API.
</td>
</tr>
<tr>
<td><code class="code">void *ts_resource_ex(ts_rsrc_id id, THREAD_T *th_id)</code></td>
<td>
Fetches a resource by previously allocated <code class="code">id</code> from the entries created by the specified thread identifed by <code class="code">th_id</code>.
</td>
</tr>
<tr>
<td>
<code class="code">void *ts_resource(ts_rsrc_id id)</code>
</td>
<td>
Fetches a resource by previously allocated <code class="code">id</code> from the entries created by the calling thread.
</td>
</tr>
<tr>
<td><code class="code">void ts_free_thread(void)</code></td>
<td>
Destroys and frees the entries for the calling thread, currently this API is only used by ISAPI module.
</td>
</tr>
<tr>
<td>
<code class="code">void ts_free_id(ts_rsrc_id id)</code>
</td>
<td>
Destroys the resource identified by previously allocated <code class="code">id</code>. Module globals are cleaned up in ZTS mode using this API.
</td>
</tr>
</tbody>
</table>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="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.</span>
</p></blockquote>
<table id="internals2.memory.tsrm.mapis" class="doctable table">
<caption><strong>TSRM Mutex API</strong></caption>
<thead>
<tr>
<th>Prototype</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><code class="code">MUTEX_T tsrm_mutex_alloc(void)</code></td>
<td>Allocates and returns a suitable MUTEX_T for the environment.</td>
</tr>
<tr>
<td><code class="code">int tsrm_mutex_lock(MUTEX_T mutexp)</code></td>
<td>
Locks <code class="code">mutexp</code> for the calling thread.
</td>
</tr>
<tr>
<td><code class="code">int tsrm_mutex_unlock(MUTEX_T mutexp)</code></td>
<td>
Unlocks <code class="code">mutexp</code> for the calling thread.
</td>
</tr>
<tr>
<td><code class="code">void tsrm_mutex_free(MUTEX_T mutexp);</code></td>
<td>
Destroys and frees the (unlocked) and previously allocated <code class="code">mutexp</code>.
</td>
</tr>
</tbody>
</table>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="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.</span>
</p></blockquote>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="internals2.memory.persistence.html">Data persistence</a></div>
<div class="next" style="text-align: right; float: right;"><a href="internals2.variables.html">Working with Variables</a></div>
<div class="up"><a href="internals2.memory.html">Memory management</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
