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