thread_safety.html.en revision ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7
22d5d84393d960a2027f472036f3fee15d7dbce9nd<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
22d5d84393d960a2027f472036f3fee15d7dbce9nd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
22d5d84393d960a2027f472036f3fee15d7dbce9nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
22d5d84393d960a2027f472036f3fee15d7dbce9nd This file is generated from xml source: DO NOT EDIT
22d5d84393d960a2027f472036f3fee15d7dbce9nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<title>Apache 2.0 Thread Safety Issues - Apache HTTP Server</title>
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<link href="/images/favicon.ico" rel="shortcut icon" /></head>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.1</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Apache 2.0 Thread Safety Issues</h1>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<p><span>Available Languages: </span><a href="/en/developer/thread_safety.html" title="English"> en </a></p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>When using any of the threaded mpms in Apache 2.0 it is important
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim that every function called from Apache be thread safe. When linking in 3rd
22d5d84393d960a2027f472036f3fee15d7dbce9nd party extensions it can be difficult to determine whether the resulting
22d5d84393d960a2027f472036f3fee15d7dbce9nd server will be thread safe. Casual testing generally won't tell you this
22d5d84393d960a2027f472036f3fee15d7dbce9nd either as thread safety problems can lead to subtle race conditons that
22d5d84393d960a2027f472036f3fee15d7dbce9nd may only show up in certain conditions under heavy load.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#variables">Global and static variables</a></li>
ecdc51f25765b81b6d07389c6fa02a9529411f5drbowen<li><img alt="" src="/images/down.gif" /> <a href="#errno">errno</a></li>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<li><img alt="" src="/images/down.gif" /> <a href="#functions">Common standard troublesome functions</a></li>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<li><img alt="" src="/images/down.gif" /> <a href="#commonlibs">Common 3rd Party Libraries</a></li>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<li><img alt="" src="/images/down.gif" /> <a href="#liblist">Library List</a></li>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<h2><a name="variables" id="variables">Global and static variables</a></h2>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>When writing your module or when trying to determine if a module or
22d5d84393d960a2027f472036f3fee15d7dbce9nd 3rd party library is thread safe there are some common things to keep in
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>First, you need to recognize that in a threaded model each individual
22d5d84393d960a2027f472036f3fee15d7dbce9nd thread has its own program counter, stack and registers. Local variables
22d5d84393d960a2027f472036f3fee15d7dbce9nd live on the stack, so those are fine. You need to watch out for any
22d5d84393d960a2027f472036f3fee15d7dbce9nd static or global variables. This doesn't mean that you are absolutely not
22d5d84393d960a2027f472036f3fee15d7dbce9nd allowed to use static or global variables. There are times when you
22d5d84393d960a2027f472036f3fee15d7dbce9nd actually want something to affect all threads, but generally you need to
22d5d84393d960a2027f472036f3fee15d7dbce9nd avoid using them if you want your code to be thread safe.</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>In the case where you have a global variable that needs to be global and
22d5d84393d960a2027f472036f3fee15d7dbce9nd accessed by all threads, be very careful when you update it. If, for
22d5d84393d960a2027f472036f3fee15d7dbce9nd example, it is an incrementing counter, you need to atomically increment
22d5d84393d960a2027f472036f3fee15d7dbce9nd it to avoid race conditions with other threads. You do this using a mutex
22d5d84393d960a2027f472036f3fee15d7dbce9nd (mutual exclusion). Lock the mutex, read the current value, increment it
6a40b378ef57ef1dbc193c1afd600fa591d65ac9pctony and write it back and then unlock the mutex. Any other thread that wants
22d5d84393d960a2027f472036f3fee15d7dbce9nd to modify the value has to first check the mutex and block until it is
22d5d84393d960a2027f472036f3fee15d7dbce9nd cleared.</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a look
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim at the <code>apr_atomic_<var>*</var></code> functions and the
ac1a656380fb9c5636a1f41b7e284f8eb2d60011chrisd <code>apr_thread_mutex_<var>*</var></code> functions.</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>This is a common global variable that holds the error number of the
22d5d84393d960a2027f472036f3fee15d7dbce9nd last error that occurred. If one thread calls a low-level function that
22d5d84393d960a2027f472036f3fee15d7dbce9nd sets errno and then another thread checks it, we are bleeding error
22d5d84393d960a2027f472036f3fee15d7dbce9nd numbers from one thread into another. To solve this, make sure your
bd43fc31993cfc191e744a9490481f4294894099covener module or library defines <code>_REENTRANT</code> or is compiled with
bd43fc31993cfc191e744a9490481f4294894099covener <code>-D_REENTRANT</code>. This will make errno a per-thread variable
bd43fc31993cfc191e744a9490481f4294894099covener and should hopefully be transparent to the code. It does this by doing
bd43fc31993cfc191e744a9490481f4294894099covener something like this:</p>
bd43fc31993cfc191e744a9490481f4294894099covener #define errno (*(__errno_location()))
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>which means that accessing errno will call
22d5d84393d960a2027f472036f3fee15d7dbce9nd <code>__errno_location()</code> which is provided by the libc. Setting
22d5d84393d960a2027f472036f3fee15d7dbce9nd <code>_REENTRANT</code> also forces redefinition of some other functions
22d5d84393d960a2027f472036f3fee15d7dbce9nd to their <code><var>*</var>_r</code> equivalents and sometimes changes
22d5d84393d960a2027f472036f3fee15d7dbce9nd the common <code>getc</code>/<code>putc</code> macros into safer function
22d5d84393d960a2027f472036f3fee15d7dbce9nd calls. Check your libc documentation for specifics. Instead of, or in
22d5d84393d960a2027f472036f3fee15d7dbce9nd addition to <code>_REENTRANT</code> the symbols that may affect this are
81c816b41dff7591b248d78309189055e0c9ebectakashi <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
81c816b41dff7591b248d78309189055e0c9ebectakashi</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<h2><a name="functions" id="functions">Common standard troublesome functions</a></h2>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>Not only do things have to be thread safe, but they also have to be
22d5d84393d960a2027f472036f3fee15d7dbce9nd reentrant. <code>strtok()</code> is an obvious one. You call it the first
22d5d84393d960a2027f472036f3fee15d7dbce9nd time with your delimiter which it then remembers and on each subsequent
22d5d84393d960a2027f472036f3fee15d7dbce9nd call it returns the next token. Obviously if multiple threads are
22d5d84393d960a2027f472036f3fee15d7dbce9nd calling it you will have a problem. Most systems have a reentrant version
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper of of the function called <code>strtok_r()</code> where you pass in an
22d5d84393d960a2027f472036f3fee15d7dbce9nd extra argument which contains an allocated <code>char *</code> which the
22d5d84393d960a2027f472036f3fee15d7dbce9nd function will use instead of its own static storage for maintaining
22d5d84393d960a2027f472036f3fee15d7dbce9nd the tokenizing state. If you are using <a href="http://apr.apache.org/">APR</a> you can use <code>apr_strtok()</code>.</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p><code>crypt()</code> is another function that tends to not be reentrant,
22d5d84393d960a2027f472036f3fee15d7dbce9nd so if you run across calls to that function in a library, watch out. On
22d5d84393d960a2027f472036f3fee15d7dbce9nd some systems it is reentrant though, so it is not always a problem. If
22d5d84393d960a2027f472036f3fee15d7dbce9nd your system has <code>crypt_r()</code> chances are you should be using
22d5d84393d960a2027f472036f3fee15d7dbce9nd that, or if possible simply avoid the whole mess by using md5 instead.</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<h2><a name="commonlibs" id="commonlibs">Common 3rd Party Libraries</a></h2>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>The following is a list of common libraries that are used by 3rd party
22d5d84393d960a2027f472036f3fee15d7dbce9nd Apache modules. You can check to see if your module is using a potentially
22d5d84393d960a2027f472036f3fee15d7dbce9nd unsafe library by using tools such as <code>ldd(1)</code> and
22d5d84393d960a2027f472036f3fee15d7dbce9nd <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for example,
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh try this:</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)<br />
a330659fa32865eb8521adaccf5d9b75687b9aebtrawick libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)<br />
a330659fa32865eb8521adaccf5d9b75687b9aebtrawick libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)<br />
ecdc51f25765b81b6d07389c6fa02a9529411f5drbowen libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)<br />
22d5d84393d960a2027f472036f3fee15d7dbce9nd libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)<br />
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)<br />
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)
22d5d84393d960a2027f472036f3fee15d7dbce9nd <p>In addition to these libraries you will need to have a look at any
22d5d84393d960a2027f472036f3fee15d7dbce9nd libraries linked statically into the module. You can use <code>nm(1)</code>
22d5d84393d960a2027f472036f3fee15d7dbce9nd to look for individual symbols in the module.</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh<h2><a name="liblist" id="liblist">Library List</a></h2>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh <p>Please drop a note to <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh if you have additions or corrections to this list.</p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <table class="bordered"><tr class="header"><th>Library</th><th>Version</th><th>Thread Safe?</th><th>Notes</th></tr>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://aspell.sourceforge.net/">ASpell/PSpell</a></td>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh<tr class="odd"><td><a href="http://www.sleepycat.com/">Berkeley DB</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <td>Be careful about sharing a connection across threads.</td></tr>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://sources.redhat.com/bzip2/index.html">bzip2</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <td>Both low-level and high-level APIs are thread-safe. However,
22d5d84393d960a2027f472036f3fee15d7dbce9nd high-level API requires thread-safe access to errno.</td></tr>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh<tr class="odd"><td><a href="http://cr.yp.to/cdb.html">cdb</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://www.washington.edu/imap/">C-Client</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <code>gethostbyname()</code> which are not thread-safe on most C
22d5d84393d960a2027f472036f3fee15d7dbce9nd library implementations. c-client's static data is meant to be shared
22d5d84393d960a2027f472036f3fee15d7dbce9nd <code>gethostbyname()</code> are thread-safe on your OS, c-client
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh<tr class="odd"><td><a href="http://www.fastio.com/">cpdflib</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://www.ijg.org/files/">libcrypt</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr class="odd"><td><a href="http://expat.sourceforge.net/">Expat</a></td>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <td>Need a separate parser instance per thread</td></tr>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<tr><td><a href="http://www.freetds.org/">FreeTDS</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr class="odd"><td><a href="http://www.freetype.org/">FreeType</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh<tr class="odd"><td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td>
6f10385908fbdfd4849e4bc50e690ee54c62f2cdhumbedooh<tr><td><a href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr class="odd"><td><a href="http://www.imagemagick.org/">ImageMagick</a></td>
bd43fc31993cfc191e744a9490481f4294894099covener <td>ImageMagick docs claim it is thread safe since version 5.2.2 (see <a href="http://www.cise.ufl.edu/depot/www/ImageMagick/www/Changelog.html">Change log</a>).
bd43fc31993cfc191e744a9490481f4294894099covener<tr><td><a href="http://www.enlightenment.org/pages/imlib2.html">Imlib2</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr class="odd"><td><a href="http://www.ijg.org/files/">libjpeg</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://mysql.com">libmysqlclient</a></td>
81c816b41dff7591b248d78309189055e0c9ebectakashi <td>Use mysqlclient_r library variant to ensure thread-safety. For
22d5d84393d960a2027f472036f3fee15d7dbce9nd more information, please read <a href="http://www.mysql.com/doc/en/Threaded_clients.html">http://www.mysql.com/doc/en/Threaded_clients.html</a>.</td></tr>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr class="odd"><td><a href="http://www.opaque.net/ming/">Ming</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr class="odd"><td><a href="http://www.openldap.org/">OpenLDAP</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr><td><a href="http://www.openssl.org/">OpenSSL</a></td>
22d5d84393d960a2027f472036f3fee15d7dbce9nd <td>Requires proper usage of <code>CRYPTO_num_locks</code>,
22d5d84393d960a2027f472036f3fee15d7dbce9nd<tr class="odd"><td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper <td>PDFLib docs claim it is thread safe; changes.txt indicates it
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper has been partially thread-safe since V1.91: <a href="http://www.pdflib.com/products/pdflib/index.html">http://www.pdflib.com/products/pdflib/index.html</a>.</td></tr>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper<tr class="odd"><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper<tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper<tr class="odd"><td><a href="http://www.postgresql.org/idocs/index.php?libpq-threading.html">libpq (PostgreSQL)</a></td>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper <td>Don't share connections across threads and watch out for
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper<tr><td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml">Sablotron</a></td>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper<tr class="odd"><td><a href="http://www.gzip.org/zlib/">zlib</a></td>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper <td>Relies upon thread-safe zalloc and zfree functions Default is to
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper use libc's calloc/free which are thread-safe.</td></tr>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<p><span>Available Languages: </span><a href="/en/developer/thread_safety.html" title="English"> en </a></p>
22d5d84393d960a2027f472036f3fee15d7dbce9nd<p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
b57e88079429c92f4de900e6ac0b27fc3d234b97pepper<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>