thread_safety.html.en revision 205f749042ed530040a4f0080dbcb47ceae8a374
f73f2c2fae0ded6c8273c28d025ba8aa8136a0fend<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
f73f2c2fae0ded6c8273c28d025ba8aa8136a0fend<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
f73f2c2fae0ded6c8273c28d025ba8aa8136a0fend XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive This file is generated from xml source: DO NOT EDIT
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<title>Apache HTTP Server 2.x Thread Safety Issues - Apache HTTP Server Version 2.5</title>
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
7946ba46eb606490ae263e099e13313b56ef68e4erikabele<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<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" />
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<script src="/style/scripts/prettify.min.js" type="text/javascript">
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<link href="/images/favicon.ico" rel="shortcut icon" /></head>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.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>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<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>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p><span>Available Languages: </span><a href="/en/developer/thread_safety.html" title="English"> en </a></p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>When using any of the threaded mpms in the Apache HTTP Server 2.x it is important
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd that every function called from Apache be thread safe. When linking in 3rd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd party extensions it can be difficult to determine whether the resulting
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd server will be thread safe. Casual testing generally won't tell you this
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd either as thread safety problems can lead to subtle race conditions that
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd may only show up in certain conditions under heavy load.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#variables">Global and static variables</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#errno">errno</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#functions">Common standard troublesome functions</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#commonlibs">Common 3rd Party Libraries</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#liblist">Library List</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="variables" id="variables">Global and static variables</a></h2>
aedd0bf93c729eb723b1eeffccf46bf0117ff0ederikabele <p>When writing your module or when trying to determine if a module or
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd 3rd party library is thread safe there are some common things to keep in
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>First, you need to recognize that in a threaded model each individual
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd thread has its own program counter, stack and registers. Local variables
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd live on the stack, so those are fine. You need to watch out for any
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd static or global variables. This doesn't mean that you are absolutely not
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd allowed to use static or global variables. There are times when you
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd actually want something to affect all threads, but generally you need to
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd avoid using them if you want your code to be thread safe.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>In the case where you have a global variable that needs to be global and
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd accessed by all threads, be very careful when you update it. If, for
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd example, it is an incrementing counter, you need to atomically increment
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd it to avoid race conditions with other threads. You do this using a mutex
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd (mutual exclusion). Lock the mutex, read the current value, increment it
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd and write it back and then unlock the mutex. Any other thread that wants
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd to modify the value has to first check the mutex and block until it is
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd cleared.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a look
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd at the <code>apr_atomic_<var>*</var></code> functions and the
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code>apr_thread_mutex_<var>*</var></code> functions.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>This is a common global variable that holds the error number of the
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd last error that occurred. If one thread calls a low-level function that
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd sets errno and then another thread checks it, we are bleeding error
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd numbers from one thread into another. To solve this, make sure your
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd module or library defines <code>_REENTRANT</code> or is compiled with
89ccb0f86491cc768e39f5c3c95a23f45a81eb3ckess <code>-D_REENTRANT</code>. This will make errno a per-thread variable
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd and should hopefully be transparent to the code. It does this by doing
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd something like this:</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd #define errno (*(__errno_location()))
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>which means that accessing errno will call
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code>__errno_location()</code> which is provided by the libc. Setting
89ccb0f86491cc768e39f5c3c95a23f45a81eb3ckess <code>_REENTRANT</code> also forces redefinition of some other functions
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd to their <code><var>*</var>_r</code> equivalents and sometimes changes
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd the common <code>getc</code>/<code>putc</code> macros into safer function
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd calls. Check your libc documentation for specifics. Instead of, or in
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd addition to <code>_REENTRANT</code> the symbols that may affect this are
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="functions" id="functions">Common standard troublesome functions</a></h2>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>Not only do things have to be thread safe, but they also have to be
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd reentrant. <code>strtok()</code> is an obvious one. You call it the first
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd time with your delimiter which it then remembers and on each subsequent
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd call it returns the next token. Obviously if multiple threads are
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd calling it you will have a problem. Most systems have a reentrant version
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd of of the function called <code>strtok_r()</code> where you pass in an
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd extra argument which contains an allocated <code>char *</code> which the
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd function will use instead of its own static storage for maintaining
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd the tokenizing state. If you are using <a href="http://apr.apache.org/">APR</a> you can use <code>apr_strtok()</code>.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p><code>crypt()</code> is another function that tends to not be reentrant,
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd so if you run across calls to that function in a library, watch out. On
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd some systems it is reentrant though, so it is not always a problem. If
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd your system has <code>crypt_r()</code> chances are you should be using
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd that, or if possible simply avoid the whole mess by using md5 instead.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="commonlibs" id="commonlibs">Common 3rd Party Libraries</a></h2>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>The following is a list of common libraries that are used by 3rd party
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd Apache modules. You can check to see if your module is using a potentially
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd unsafe library by using tools such as <code>ldd(1)</code> and
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for example,
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd try this:</p>
8af1f06ba59fdda01b4a5c2fea560c2bf0569addslive libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)<br />
f73f2c2fae0ded6c8273c28d025ba8aa8136a0fend libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>In addition to these libraries you will need to have a look at any
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd libraries linked statically into the module. You can use <code>nm(1)</code>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd to look for individual symbols in the module.</p>
cd9f05dfac570b44f26f531e01869e679c45401berikabele</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<p>Please drop a note to <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a>
<table class="bordered"><tr class="header"><th>Library</th><th>Version</th><th>Thread Safe?</th><th>Notes</th></tr>
<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>).
<tr class="odd"><td><a href="http://www.enlightenment.org/p.php?p=about/efl&l=en">Imlib2</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>
</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>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
var comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/thread_safety.html';
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
<p class="apache">Copyright 2015 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/quickreference.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[//><!--