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