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

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="thread_safety.xml.meta">
  24 <parentdocument href="./">Developer Documentation</parentdocument>
  25
  26 <title>Apache HTTP Server 2.x Thread Safety Issues</title>
  27
  28 <summary>
  29     <p>When using any of the threaded mpms in the Apache HTTP Server 2.x it is important
  30     that every function called from Apache be thread safe.  When linking in 3rd
  31     party extensions it can be difficult to determine whether the resulting
  32     server will be thread safe.  Casual testing generally won't tell you this
  33     either as thread safety problems can lead to subtle race conditions that
  34     may only show up in certain conditions under heavy load.</p>
  35 </summary>
  36
  37 <section id="variables"><title>Global and static variables</title>
  38     <p>When writing your module or when trying to determine if a module or
  39     3rd party library is thread safe there are some common things to keep in
  40     mind.</p>
  41
  42     <p>First, you need to recognize that in a threaded model each individual
  43     thread has its own program counter, stack and registers.  Local variables
  44     live on the stack, so those are fine.  You need to watch out for any
  45     static or global variables.  This doesn't mean that you are absolutely not
  46     allowed to use static or global variables.  There are times when you
  47     actually want something to affect all threads, but generally you need to
  48     avoid using them if you want your code to be thread safe.</p>
  49
  50     <p>In the case where you have a global variable that needs to be global and
  51     accessed by all threads, be very careful when you update it.  If, for
  52     example, it is an incrementing counter, you need to atomically increment
  53     it to avoid race conditions with other threads.  You do this using a mutex
  54     (mutual exclusion). Lock the mutex, read the current value, increment it
  55     and write it back and then unlock the mutex.  Any other thread that wants
  56     to modify the value has to first check the mutex and block until it is
  57     cleared.</p>
  58
  59     <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a look
  60     at the <code>apr_atomic_<var>*</var></code> functions and the
  61     <code>apr_thread_mutex_<var>*</var></code> functions.</p>
  62     <!-- [would probably be a good idea to add an example here] -->
  63 </section>
  64
  65 <section id="errno"><title>errno</title>
  66     <p>This is a common global variable that holds the error number of the
  67     last error that occurred. If one thread calls a low-level function that
  68     sets errno and then another thread checks it, we are bleeding error
  69     numbers from one thread into another.  To solve this, make sure your
  70     module or library defines <code>_REENTRANT</code> or is compiled with
  71     <code>-D_REENTRANT</code>. This will make errno a per-thread variable
  72     and should hopefully be transparent to the code. It does this by doing
  73     something like this:</p>
  74
  75     <example>
  76       #define errno (*(__errno_location()))
  77     </example>
  78
  79     <p>which means that accessing errno will call
  80     <code>__errno_location()</code> which is provided by the libc. Setting
  81     <code>_REENTRANT</code> also forces redefinition of some other functions
  82     to their <code><var>*</var>_r</code> equivalents and sometimes changes
  83     the common <code>getc</code>/<code>putc</code> macros into safer function
  84     calls.  Check your libc documentation for specifics.  Instead of, or in
  85     addition to <code>_REENTRANT</code> the symbols that may affect this are
  86     <code>_POSIX_C_SOURCE</code>, <code>_THREAD_SAFE</code>,
  87     <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
  88 </section>
  89
  90 <section id="functions"><title>Common standard troublesome functions</title>
  91     <p>Not only do things have to be thread safe, but they also have to be
  92     reentrant. <code>strtok()</code> is an obvious one. You call it the first
  93     time with your delimiter which it then remembers and on each subsequent
  94     call it returns the next token.  Obviously if multiple threads are
  95     calling it you will have a problem.  Most systems have a reentrant version
  96     of of the function called <code>strtok_r()</code> where you pass in an
  97     extra argument which contains an allocated <code>char *</code> which the
  98     function will use instead of its own static storage for maintaining
  99     the tokenizing state. If you are using <a href="http://apr.apache.org/"
 100     >APR</a> you can use <code>apr_strtok()</code>.</p>
 101
 102     <p><code>crypt()</code> is another function that tends to not be reentrant,
 103     so if you run across calls to that function in a library, watch out. On
 104     some systems it is reentrant though, so it is not always a problem. If
 105     your system has <code>crypt_r()</code> chances are you should be using
 106     that, or if possible simply avoid the whole mess by using md5 instead.</p>
 107     <!-- [I don't see an apr_crypt() function.] -->
 108 </section>
 109
 110 <section id="commonlibs"><title>Common 3rd Party Libraries</title>
 111     <p>The following is a list of common libraries that are used by 3rd party
 112     Apache modules.  You can check to see if your module is using a potentially
 113     unsafe library by using tools such as <code>ldd(1)</code> and
 114     <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for example,
 115     try this:</p>
 116
 117     <example>
 118       % ldd libphp4.so<br />
 119       libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)<br />
 120       libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)<br />
 121       libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)<br />
 122       libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)<br />
 123       libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)<br />
 124       libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)<br />
 125       libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)<br />
 126       libming.so => /usr/lib/libming.so (0x40449000)<br />
 127       libm.so.6 => /lib/libm.so.6 (0x40487000)<br />
 128       libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)<br />
 129       libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)<br />
 130       libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)<br />
 131       libssl.so.2 => /lib/libssl.so.2 (0x40532000)<br />
 132       libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)<br />
 133       libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)<br />
 134       libdl.so.2 => /lib/libdl.so.2 (0x40634000)<br />
 135       libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)<br />
 136       libc.so.6 => /lib/libc.so.6 (0x4064b000)<br />
 137       /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)
 138     </example>
 139
 140     <p>In addition to these libraries you will need to have a look at any
 141     libraries linked statically into the module. You can use <code>nm(1)</code>
 142     to look for individual symbols in the module.</p>
 143 </section>
 144
 145 <section id="liblist"><title>Library List</title>
 146     <p>Please drop a note to <a
 147     href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a>
 148     if you have additions or corrections to this list.</p>
 149
 150     <table style="zebra" border="1">
 151     <tr><th>Library</th><th>Version</th><th>Thread Safe?</th><th>Notes</th></tr>
 152     <tr><td><a href="http://aspell.sourceforge.net/">ASpell/PSpell</a></td>
 153         <td> </td>
 154         <td>?</td>
 155         <td> </td></tr>
 156     <tr><td><a href="http://www.sleepycat.com/">Berkeley DB</a></td>
 157         <td>3.x, 4.x</td>
 158         <td>Yes</td>
 159         <td>Be careful about sharing a connection across threads.</td></tr>
 160     <tr><td><a href="http://sources.redhat.com/bzip2/index.html">bzip2</a></td>
 161         <td> </td>
 162         <td>Yes</td>
 163         <td>Both low-level and high-level APIs are thread-safe. However,
 164         high-level API requires thread-safe access to errno.</td></tr>
 165     <tr><td><a href="http://cr.yp.to/cdb.html">cdb</a></td>
 166         <td> </td>
 167         <td>?</td>
 168         <td> </td></tr>
 169     <tr><td><a href="http://www.washington.edu/imap/">C-Client</a></td>
 170         <td> </td>
 171         <td>Perhaps</td>
 172         <td>c-client uses <code>strtok()</code> and
 173         <code>gethostbyname()</code> which are not thread-safe on most C
 174         library implementations.  c-client's static data is meant to be shared
 175         across threads. If <code>strtok()</code> and
 176         <code>gethostbyname()</code> are thread-safe on your OS, c-client
 177         <em>may</em> be thread-safe.</td></tr>
 178     <tr><td><a href="http://www.ijg.org/files/">libcrypt</a></td>
 179         <td> </td>
 180         <td>?</td>
 181         <td> </td></tr>
 182     <tr><td><a href="http://expat.sourceforge.net/">Expat</a></td>
 183         <td> </td>
 184         <td>Yes</td>
 185         <td>Need a separate parser instance per thread</td></tr>
 186     <tr><td><a href="http://www.freetds.org/">FreeTDS</a></td>
 187         <td> </td>
 188         <td>?</td>
 189         <td> </td></tr>
 190     <tr><td><a href="http://www.freetype.org/">FreeType</a></td>
 191         <td> </td>
 192         <td>?</td>
 193         <td> </td></tr>
 194     <tr><td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td>
 195         <td> </td>
 196         <td>?</td>
 197         <td> </td></tr>
 198     <tr><td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td>
 199         <td> </td>
 200         <td>?</td>
 201         <td> </td></tr>
 202     <tr><td><a href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td>
 203         <td> </td>
 204         <td>No</td>
 205         <td>Errors returned via a static <code>gdbm_error</code>
 206         variable</td></tr>
 207     <tr><td><a href="http://www.imagemagick.org/">ImageMagick</a></td>
 208         <td>5.2.2</td>
 209         <td>Yes</td>
 210         <td>ImageMagick docs claim it is thread safe since version 5.2.2 (see <a
 211         href="http://www.imagemagick.com/www/changelog.html"
 212         >Change log</a>).
 213         </td></tr>
 214     <tr><td><a href="http://www.enlightenment.org/p.php?p=about/efl&amp;l=en"
 215         >Imlib2</a></td>
 216         <td> </td>
 217         <td>?</td>
 218         <td> </td></tr>
 219     <tr><td><a href="http://www.ijg.org/files/">libjpeg</a></td>
 220         <td>v6b</td>
 221         <td>?</td>
 222         <td> </td></tr>
 223     <tr><td><a href="http://mysql.com">libmysqlclient</a></td>
 224         <td> </td>
 225         <td>Yes</td>
 226         <td>Use mysqlclient_r library variant to ensure thread-safety.  For
 227             more information, please read <a
 228             href="http://dev.mysql.com/doc/mysql/en/Threaded_clients.html"
 229             >http://dev.mysql.com/doc/mysql/en/Threaded_clients.html</a>.</td></tr>
 230     <tr><td><a href="http://www.opaque.net/ming/">Ming</a></td>
 231         <td>0.2a</td>
 232         <td>?</td>
 233         <td> </td></tr>
 234     <tr><td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td>
 235         <td>5.0.x</td>
 236         <td>?</td>
 237         <td> </td></tr>
 238     <tr><td><a href="http://www.openldap.org/">OpenLDAP</a></td>
 239         <td>2.1.x</td>
 240         <td>Yes</td>
 241         <td>Use <code>ldap_r</code> library variant to ensure
 242         thread-safety.</td></tr>
 243     <tr><td><a href="http://www.openssl.org/">OpenSSL</a></td>
 244         <td>0.9.6g</td>
 245         <td>Yes</td>
 246         <td>Requires proper usage of <code>CRYPTO_num_locks</code>,
 247         <code>CRYPTO_set_locking_callback</code>,
 248         <code>CRYPTO_set_id_callback</code></td></tr>
 249     <tr><td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td>
 250         <td>8.x,9.x</td>
 251         <td>?</td>
 252         <td> </td></tr>
 253     <tr><td><a href="http://pdflib.com/">pdflib</a></td>
 254         <td>5.0.x</td>
 255         <td>Yes</td>
 256         <td>PDFLib docs claim it is thread safe; changes.txt indicates it
 257             has been partially thread-safe since V1.91: <a
 258             href="http://www.pdflib.com/products/pdflib-family/pdflib/"
 259             >http://www.pdflib.com/products/pdflib-family/pdflib/</a>.</td></tr>
 260     <tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
 261         <td>1.0.x</td>
 262         <td>?</td>
 263         <td> </td></tr>
 264     <tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
 265         <td>1.2.x</td>
 266         <td>?</td>
 267         <td> </td></tr>
 268     <tr><td><a
 269         href="http://www.postgresql.org/docs/8.4/static/libpq-threading.html"
 270         >libpq (PostgreSQL)</a></td>
 271         <td>8.x</td>
 272         <td>Yes</td>
 273         <td>Don't share connections across threads and watch out for
 274         <code>crypt()</code> calls</td></tr>
 275     <tr><td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml"
 276         >Sablotron</a></td>
 277         <td>0.95</td>
 278         <td>?</td>
 279         <td></td></tr>
 280     <tr><td><a href="http://www.gzip.org/zlib/">zlib</a></td>
 281         <td>1.1.4</td>
 282         <td>Yes</td>
 283         <td>Relies upon thread-safe zalloc and zfree functions  Default is to
 284         use libc's calloc/free which are thread-safe.</td></tr>
 285     </table>
 286 </section>
 287 </manualpage>