granicus.if.org Git - apache/blob - docs/manual/developer/thread_safety.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Apache HTTP Server 2.x Thread Safety Issues - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  18 <p class="apache">Apache HTTP Server Version 2.5</p>
  19 <img alt="" src="../images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  21 <div id="path">
  22 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Apache HTTP Server 2.x Thread Safety Issues</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/developer/thread_safety.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26
  27     <p>When using any of the threaded mpms in the Apache HTTP Server 2.x it is important
  28     that every function called from Apache be thread safe.  When linking in 3rd
  29     party extensions it can be difficult to determine whether the resulting
  30     server will be thread safe.  Casual testing generally won't tell you this
  31     either as thread safety problems can lead to subtle race conditions that
  32     may only show up in certain conditions under heavy load.</p>
  33 </div>
  34 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#variables">Global and static variables</a></li>
  35 <li><img alt="" src="../images/down.gif" /> <a href="#errno">errno</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#functions">Common standard troublesome functions</a></li>
  37 <li><img alt="" src="../images/down.gif" /> <a href="#commonlibs">Common 3rd Party Libraries</a></li>
  38 <li><img alt="" src="../images/down.gif" /> <a href="#liblist">Library List</a></li>
  39 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  40 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  41 <div class="section">
  42 <h2><a name="variables" id="variables">Global and static variables</a></h2>
  43     <p>When writing your module or when trying to determine if a module or
  44     3rd party library is thread safe there are some common things to keep in
  45     mind.</p>
  46
  47     <p>First, you need to recognize that in a threaded model each individual
  48     thread has its own program counter, stack and registers.  Local variables
  49     live on the stack, so those are fine.  You need to watch out for any
  50     static or global variables.  This doesn't mean that you are absolutely not
  51     allowed to use static or global variables.  There are times when you
  52     actually want something to affect all threads, but generally you need to
  53     avoid using them if you want your code to be thread safe.</p>
  54
  55     <p>In the case where you have a global variable that needs to be global and
  56     accessed by all threads, be very careful when you update it.  If, for
  57     example, it is an incrementing counter, you need to atomically increment
  58     it to avoid race conditions with other threads.  You do this using a mutex
  59     (mutual exclusion). Lock the mutex, read the current value, increment it
  60     and write it back and then unlock the mutex.  Any other thread that wants
  61     to modify the value has to first check the mutex and block until it is
  62     cleared.</p>
  63
  64     <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a look
  65     at the <code>apr_atomic_<var>*</var></code> functions and the
  66     <code>apr_thread_mutex_<var>*</var></code> functions.</p>
  67
  68 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  69 <div class="section">
  70 <h2><a name="errno" id="errno">errno</a></h2>
  71     <p>This is a common global variable that holds the error number of the
  72     last error that occurred. If one thread calls a low-level function that
  73     sets errno and then another thread checks it, we are bleeding error
  74     numbers from one thread into another.  To solve this, make sure your
  75     module or library defines <code>_REENTRANT</code> or is compiled with
  76     <code>-D_REENTRANT</code>. This will make errno a per-thread variable
  77     and should hopefully be transparent to the code. It does this by doing
  78     something like this:</p>
  79
  80     <div class="example"><p><code>
  81       #define errno (*(__errno_location()))
  82     </code></p></div>
  83
  84     <p>which means that accessing errno will call
  85     <code>__errno_location()</code> which is provided by the libc. Setting
  86     <code>_REENTRANT</code> also forces redefinition of some other functions
  87     to their <code><var>*</var>_r</code> equivalents and sometimes changes
  88     the common <code>getc</code>/<code>putc</code> macros into safer function
  89     calls.  Check your libc documentation for specifics.  Instead of, or in
  90     addition to <code>_REENTRANT</code> the symbols that may affect this are
  91     <code>_POSIX_C_SOURCE</code>, <code>_THREAD_SAFE</code>,
  92     <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
  93 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  94 <div class="section">
  95 <h2><a name="functions" id="functions">Common standard troublesome functions</a></h2>
  96     <p>Not only do things have to be thread safe, but they also have to be
  97     reentrant. <code>strtok()</code> is an obvious one. You call it the first
  98     time with your delimiter which it then remembers and on each subsequent
  99     call it returns the next token.  Obviously if multiple threads are
 100     calling it you will have a problem.  Most systems have a reentrant version
 101     of of the function called <code>strtok_r()</code> where you pass in an
 102     extra argument which contains an allocated <code>char *</code> which the
 103     function will use instead of its own static storage for maintaining
 104     the tokenizing state. If you are using <a href="http://apr.apache.org/">APR</a> you can use <code>apr_strtok()</code>.</p>
 105
 106     <p><code>crypt()</code> is another function that tends to not be reentrant,
 107     so if you run across calls to that function in a library, watch out. On
 108     some systems it is reentrant though, so it is not always a problem. If
 109     your system has <code>crypt_r()</code> chances are you should be using
 110     that, or if possible simply avoid the whole mess by using md5 instead.</p>
 111
 112 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 113 <div class="section">
 114 <h2><a name="commonlibs" id="commonlibs">Common 3rd Party Libraries</a></h2>
 115     <p>The following is a list of common libraries that are used by 3rd party
 116     Apache modules.  You can check to see if your module is using a potentially
 117     unsafe library by using tools such as <code>ldd(1)</code> and
 118     <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for example,
 119     try this:</p>
 120
 121     <div class="example"><p><code>
 122       % ldd libphp4.so<br />
 123       libsablot.so.0 =&gt; /usr/local/lib/libsablot.so.0 (0x401f6000)<br />
 124       libexpat.so.0 =&gt; /usr/lib/libexpat.so.0 (0x402da000)<br />
 125       libsnmp.so.0 =&gt; /usr/lib/libsnmp.so.0 (0x402f9000)<br />
 126       libpdf.so.1 =&gt; /usr/local/lib/libpdf.so.1 (0x40353000)<br />
 127       libz.so.1 =&gt; /usr/lib/libz.so.1 (0x403e2000)<br />
 128       libpng.so.2 =&gt; /usr/lib/libpng.so.2 (0x403f0000)<br />
 129       libmysqlclient.so.11 =&gt; /usr/lib/libmysqlclient.so.11 (0x40411000)<br />
 130       libming.so =&gt; /usr/lib/libming.so (0x40449000)<br />
 131       libm.so.6 =&gt; /lib/libm.so.6 (0x40487000)<br />
 132       libfreetype.so.6 =&gt; /usr/lib/libfreetype.so.6 (0x404a8000)<br />
 133       libjpeg.so.62 =&gt; /usr/lib/libjpeg.so.62 (0x404e7000)<br />
 134       libcrypt.so.1 =&gt; /lib/libcrypt.so.1 (0x40505000)<br />
 135       libssl.so.2 =&gt; /lib/libssl.so.2 (0x40532000)<br />
 136       libcrypto.so.2 =&gt; /lib/libcrypto.so.2 (0x40560000)<br />
 137       libresolv.so.2 =&gt; /lib/libresolv.so.2 (0x40624000)<br />
 138       libdl.so.2 =&gt; /lib/libdl.so.2 (0x40634000)<br />
 139       libnsl.so.1 =&gt; /lib/libnsl.so.1 (0x40637000)<br />
 140       libc.so.6 =&gt; /lib/libc.so.6 (0x4064b000)<br />
 141       /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x80000000)
 142     </code></p></div>
 143
 144     <p>In addition to these libraries you will need to have a look at any
 145     libraries linked statically into the module. You can use <code>nm(1)</code>
 146     to look for individual symbols in the module.</p>
 147 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 148 <div class="section">
 149 <h2><a name="liblist" id="liblist">Library List</a></h2>
 150     <p>Please drop a note to <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a>
 151     if you have additions or corrections to this list.</p>
 152
 153     <table class="bordered"><tr class="header"><th>Library</th><th>Version</th><th>Thread Safe?</th><th>Notes</th></tr>
 154 <tr><td><a href="http://aspell.sourceforge.net/">ASpell/PSpell</a></td>
 155         <td> </td>
 156         <td>?</td>
 157         <td> </td></tr>
 158 <tr class="odd"><td><a href="http://www.sleepycat.com/">Berkeley DB</a></td>
 159         <td>3.x, 4.x</td>
 160         <td>Yes</td>
 161         <td>Be careful about sharing a connection across threads.</td></tr>
 162 <tr><td><a href="http://sources.redhat.com/bzip2/index.html">bzip2</a></td>
 163         <td> </td>
 164         <td>Yes</td>
 165         <td>Both low-level and high-level APIs are thread-safe. However,
 166         high-level API requires thread-safe access to errno.</td></tr>
 167 <tr class="odd"><td><a href="http://cr.yp.to/cdb.html">cdb</a></td>
 168         <td> </td>
 169         <td>?</td>
 170         <td> </td></tr>
 171 <tr><td><a href="http://www.washington.edu/imap/">C-Client</a></td>
 172         <td> </td>
 173         <td>Perhaps</td>
 174         <td>c-client uses <code>strtok()</code> and
 175         <code>gethostbyname()</code> which are not thread-safe on most C
 176         library implementations.  c-client's static data is meant to be shared
 177         across threads. If <code>strtok()</code> and
 178         <code>gethostbyname()</code> are thread-safe on your OS, c-client
 179         <em>may</em> be thread-safe.</td></tr>
 180 <tr class="odd"><td><a href="http://www.ijg.org/files/">libcrypt</a></td>
 181         <td> </td>
 182         <td>?</td>
 183         <td> </td></tr>
 184 <tr><td><a href="http://expat.sourceforge.net/">Expat</a></td>
 185         <td> </td>
 186         <td>Yes</td>
 187         <td>Need a separate parser instance per thread</td></tr>
 188 <tr class="odd"><td><a href="http://www.freetds.org/">FreeTDS</a></td>
 189         <td> </td>
 190         <td>?</td>
 191         <td> </td></tr>
 192 <tr><td><a href="http://www.freetype.org/">FreeType</a></td>
 193         <td> </td>
 194         <td>?</td>
 195         <td> </td></tr>
 196 <tr class="odd"><td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td>
 197         <td> </td>
 198         <td>?</td>
 199         <td> </td></tr>
 200 <tr><td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td>
 201         <td> </td>
 202         <td>?</td>
 203         <td> </td></tr>
 204 <tr class="odd"><td><a href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td>
 205         <td> </td>
 206         <td>No</td>
 207         <td>Errors returned via a static <code>gdbm_error</code>
 208         variable</td></tr>
 209 <tr><td><a href="http://www.imagemagick.org/">ImageMagick</a></td>
 210         <td>5.2.2</td>
 211         <td>Yes</td>
 212         <td>ImageMagick docs claim it is thread safe since version 5.2.2 (see <a href="http://www.imagemagick.com/www/changelog.html">Change log</a>).
 213         </td></tr>
 214 <tr class="odd"><td><a href="http://www.enlightenment.org/p.php?p=about/efl&amp;l=en">Imlib2</a></td>
 215         <td> </td>
 216         <td>?</td>
 217         <td> </td></tr>
 218 <tr><td><a href="http://www.ijg.org/files/">libjpeg</a></td>
 219         <td>v6b</td>
 220         <td>?</td>
 221         <td> </td></tr>
 222 <tr class="odd"><td><a href="http://mysql.com">libmysqlclient</a></td>
 223         <td> </td>
 224         <td>Yes</td>
 225         <td>Use mysqlclient_r library variant to ensure thread-safety.  For
 226             more information, please read <a href="http://dev.mysql.com/doc/mysql/en/Threaded_clients.html">http://dev.mysql.com/doc/mysql/en/Threaded_clients.html</a>.</td></tr>
 227 <tr><td><a href="http://www.opaque.net/ming/">Ming</a></td>
 228         <td>0.2a</td>
 229         <td>?</td>
 230         <td> </td></tr>
 231 <tr class="odd"><td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td>
 232         <td>5.0.x</td>
 233         <td>?</td>
 234         <td> </td></tr>
 235 <tr><td><a href="http://www.openldap.org/">OpenLDAP</a></td>
 236         <td>2.1.x</td>
 237         <td>Yes</td>
 238         <td>Use <code>ldap_r</code> library variant to ensure
 239         thread-safety.</td></tr>
 240 <tr class="odd"><td><a href="http://www.openssl.org/">OpenSSL</a></td>
 241         <td>0.9.6g</td>
 242         <td>Yes</td>
 243         <td>Requires proper usage of <code>CRYPTO_num_locks</code>,
 244         <code>CRYPTO_set_locking_callback</code>,
 245         <code>CRYPTO_set_id_callback</code></td></tr>
 246 <tr><td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td>
 247         <td>8.x,9.x</td>
 248         <td>?</td>
 249         <td> </td></tr>
 250 <tr class="odd"><td><a href="http://pdflib.com/">pdflib</a></td>
 251         <td>5.0.x</td>
 252         <td>Yes</td>
 253         <td>PDFLib docs claim it is thread safe; changes.txt indicates it
 254             has been partially thread-safe since V1.91: <a href="http://www.pdflib.com/products/pdflib-family/pdflib/">http://www.pdflib.com/products/pdflib-family/pdflib/</a>.</td></tr>
 255 <tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
 256         <td>1.0.x</td>
 257         <td>?</td>
 258         <td> </td></tr>
 259 <tr class="odd"><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
 260         <td>1.2.x</td>
 261         <td>?</td>
 262         <td> </td></tr>
 263 <tr><td><a href="http://www.postgresql.org/docs/8.4/static/libpq-threading.html">libpq (PostgreSQL)</a></td>
 264         <td>8.x</td>
 265         <td>Yes</td>
 266         <td>Don't share connections across threads and watch out for
 267         <code>crypt()</code> calls</td></tr>
 268 <tr class="odd"><td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml">Sablotron</a></td>
 269         <td>0.95</td>
 270         <td>?</td>
 271         <td /></tr>
 272 <tr><td><a href="http://www.gzip.org/zlib/">zlib</a></td>
 273         <td>1.1.4</td>
 274         <td>Yes</td>
 275         <td>Relies upon thread-safe zalloc and zfree functions  Default is to
 276         use libc's calloc/free which are thread-safe.</td></tr>
 277 </table>
 278 </div></div>
 279 <div class="bottomlang">
 280 <p><span>Available Languages: </span><a href="../en/developer/thread_safety.html" title="English">&nbsp;en&nbsp;</a></p>
 281 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>This section is experimental!</strong><br />Comments placed here should not be expected
 282 to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div>
 283 <div id="disqus_thread">
 284 </div><script type="text/javascript"><!--//--><![CDATA[//><!--
 285 var lang = 'en';
 286 var disqus_shortname = 'httpd';
 287 var disqus_identifier = window.location.href.replace(/(current|trunk)/, "2.4").replace(/\/[a-z]{2}\//, "/").replace(window.location.protocol, "http:") + '.' + lang;
 288 if (disqus_identifier.indexOf("httpd.apache.org") != -1) {
 289     (function() {
 290                 var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
 291                 dsq.src = window.location.protocol + '//' + disqus_shortname + '.disqus.com/embed.js';
 292             (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
 293         })();
 294 } else {
 295     var text = document.createTextNode("Comments have been disabled for offline viewing.");
 296     document.getElementById('disqus_thread').appendChild(text);
 297 }
 298 //--><!]]></script></div><div id="footer">
 299 <p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 300 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 301 if (typeof(prettyPrint) !== undefined) {
 302     prettyPrint();
 303 }
 304 //--><!]]></script>
 305 </body></html>