1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>Apache 2.0 Thread Safety Issues - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
13 <body id="manual-page"><div id="page-header">
14 <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>
15 <p class="apache">Apache HTTP Server Version 2.3</p>
16 <img alt="" src="../images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
19 <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>
21 <p><span>Available Languages: </span><a href="../en/developer/thread_safety.html" title="English"> en </a></p>
24 <p>When using any of the threaded mpms in Apache 2.0 it is important
25 that every function called from Apache be thread safe. When linking in 3rd
26 party extensions it can be difficult to determine whether the resulting
27 server will be thread safe. Casual testing generally won't tell you this
28 either as thread safety problems can lead to subtle race conditons that
29 may only show up in certain conditions under heavy load.</p>
31 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#variables">Global and static variables</a></li>
32 <li><img alt="" src="../images/down.gif" /> <a href="#errno">errno</a></li>
33 <li><img alt="" src="../images/down.gif" /> <a href="#functions">Common standard troublesome functions</a></li>
34 <li><img alt="" src="../images/down.gif" /> <a href="#commonlibs">Common 3rd Party Libraries</a></li>
35 <li><img alt="" src="../images/down.gif" /> <a href="#liblist">Library List</a></li>
37 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
39 <h2><a name="variables" id="variables">Global and static variables</a></h2>
40 <p>When writing your module or when trying to determine if a module or
41 3rd party library is thread safe there are some common things to keep in
44 <p>First, you need to recognize that in a threaded model each individual
45 thread has its own program counter, stack and registers. Local variables
46 live on the stack, so those are fine. You need to watch out for any
47 static or global variables. This doesn't mean that you are absolutely not
48 allowed to use static or global variables. There are times when you
49 actually want something to affect all threads, but generally you need to
50 avoid using them if you want your code to be thread safe.</p>
52 <p>In the case where you have a global variable that needs to be global and
53 accessed by all threads, be very careful when you update it. If, for
54 example, it is an incrementing counter, you need to atomically increment
55 it to avoid race conditions with other threads. You do this using a mutex
56 (mutual exclusion). Lock the mutex, read the current value, increment it
57 and write it back and then unlock the mutex. Any other thread that wants
58 to modify the value has to first check the mutex and block until it is
61 <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a look
62 at the <code>apr_atomic_<var>*</var></code> functions and the
63 <code>apr_thread_mutex_<var>*</var></code> functions.</p>
65 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
67 <h2><a name="errno" id="errno">errno</a></h2>
68 <p>This is a common global variable that holds the error number of the
69 last error that occurred. If one thread calls a low-level function that
70 sets errno and then another thread checks it, we are bleeding error
71 numbers from one thread into another. To solve this, make sure your
72 module or library defines <code>_REENTRANT</code> or is compiled with
73 <code>-D_REENTRANT</code>. This will make errno a per-thread variable
74 and should hopefully be transparent to the code. It does this by doing
75 something like this:</p>
77 <div class="example"><p><code>
78 #define errno (*(__errno_location()))
81 <p>which means that accessing errno will call
82 <code>__errno_location()</code> which is provided by the libc. Setting
83 <code>_REENTRANT</code> also forces redefinition of some other functions
84 to their <code><var>*</var>_r</code> equivalents and sometimes changes
85 the common <code>getc</code>/<code>putc</code> macros into safer function
86 calls. Check your libc documentation for specifics. Instead of, or in
87 addition to <code>_REENTRANT</code> the symbols that may affect this are
88 <code>_POSIX_C_SOURCE</code>, <code>_THREAD_SAFE</code>,
89 <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
90 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
92 <h2><a name="functions" id="functions">Common standard troublesome functions</a></h2>
93 <p>Not only do things have to be thread safe, but they also have to be
94 reentrant. <code>strtok()</code> is an obvious one. You call it the first
95 time with your delimiter which it then remembers and on each subsequent
96 call it returns the next token. Obviously if multiple threads are
97 calling it you will have a problem. Most systems have a reentrant version
98 of of the function called <code>strtok_r()</code> where you pass in an
99 extra argument which contains an allocated <code>char *</code> which the
100 function will use instead of its own static storage for maintaining
101 the tokenizing state. If you are using <a href="http://apr.apache.org/">APR</a> you can use <code>apr_strtok()</code>.</p>
103 <p><code>crypt()</code> is another function that tends to not be reentrant,
104 so if you run across calls to that function in a library, watch out. On
105 some systems it is reentrant though, so it is not always a problem. If
106 your system has <code>crypt_r()</code> chances are you should be using
107 that, or if possible simply avoid the whole mess by using md5 instead.</p>
109 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
110 <div class="section">
111 <h2><a name="commonlibs" id="commonlibs">Common 3rd Party Libraries</a></h2>
112 <p>The following is a list of common libraries that are used by 3rd party
113 Apache modules. You can check to see if your module is using a potentially
114 unsafe library by using tools such as <code>ldd(1)</code> and
115 <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for example,
118 <div class="example"><p><code>
119 % ldd libphp4.so<br />
120 libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)<br />
121 libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)<br />
122 libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)<br />
123 libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)<br />
124 libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)<br />
125 libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)<br />
126 libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)<br />
127 libming.so => /usr/lib/libming.so (0x40449000)<br />
128 libm.so.6 => /lib/libm.so.6 (0x40487000)<br />
129 libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)<br />
130 libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)<br />
131 libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)<br />
132 libssl.so.2 => /lib/libssl.so.2 (0x40532000)<br />
133 libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)<br />
134 libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)<br />
135 libdl.so.2 => /lib/libdl.so.2 (0x40634000)<br />
136 libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)<br />
137 libc.so.6 => /lib/libc.so.6 (0x4064b000)<br />
138 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)
141 <p>In addition to these libraries you will need to have a look at any
142 libraries linked statically into the module. You can use <code>nm(1)</code>
143 to look for individual symbols in the module.</p>
144 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
145 <div class="section">
146 <h2><a name="liblist" id="liblist">Library List</a></h2>
147 <p>Please drop a note to <a 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>
150 <table class="bordered"><tr class="header"><th>Library</th><th>Version</th><th>Thread Safe?</th><th>Notes</th></tr>
151 <tr><td><a href="http://aspell.sourceforge.net/">ASpell/PSpell</a></td>
155 <tr class="odd"><td><a href="http://www.sleepycat.com/">Berkeley DB</a></td>
158 <td>Be careful about sharing a connection across threads.</td></tr>
159 <tr><td><a href="http://sources.redhat.com/bzip2/index.html">bzip2</a></td>
162 <td>Both low-level and high-level APIs are thread-safe. However,
163 high-level API requires thread-safe access to errno.</td></tr>
164 <tr class="odd"><td><a href="http://cr.yp.to/cdb.html">cdb</a></td>
168 <tr><td><a href="http://www.washington.edu/imap/">C-Client</a></td>
171 <td>c-client uses <code>strtok()</code> and
172 <code>gethostbyname()</code> which are not thread-safe on most C
173 library implementations. c-client's static data is meant to be shared
174 across threads. If <code>strtok()</code> and
175 <code>gethostbyname()</code> are thread-safe on your OS, c-client
176 <em>may</em> be thread-safe.</td></tr>
177 <tr class="odd"><td><a href="http://www.ijg.org/files/">libcrypt</a></td>
181 <tr><td><a href="http://expat.sourceforge.net/">Expat</a></td>
184 <td>Need a separate parser instance per thread</td></tr>
185 <tr class="odd"><td><a href="http://www.freetds.org/">FreeTDS</a></td>
189 <tr><td><a href="http://www.freetype.org/">FreeType</a></td>
193 <tr class="odd"><td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td>
197 <tr><td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td>
201 <tr class="odd"><td><a href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td>
204 <td>Errors returned via a static <code>gdbm_error</code>
206 <tr><td><a href="http://www.imagemagick.org/">ImageMagick</a></td>
209 <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>).
211 <tr class="odd"><td><a href="http://www.enlightenment.org/p.php?p=about/efl&l=en">Imlib2</a></td>
215 <tr><td><a href="http://www.ijg.org/files/">libjpeg</a></td>
219 <tr class="odd"><td><a href="http://mysql.com">libmysqlclient</a></td>
222 <td>Use mysqlclient_r library variant to ensure thread-safety. For
223 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>
224 <tr><td><a href="http://www.opaque.net/ming/">Ming</a></td>
228 <tr class="odd"><td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td>
232 <tr><td><a href="http://www.openldap.org/">OpenLDAP</a></td>
235 <td>Use <code>ldap_r</code> library variant to ensure
236 thread-safety.</td></tr>
237 <tr class="odd"><td><a href="http://www.openssl.org/">OpenSSL</a></td>
240 <td>Requires proper usage of <code>CRYPTO_num_locks</code>,
241 <code>CRYPTO_set_locking_callback</code>,
242 <code>CRYPTO_set_id_callback</code></td></tr>
243 <tr><td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td>
247 <tr class="odd"><td><a href="http://pdflib.com/">pdflib</a></td>
250 <td>PDFLib docs claim it is thread safe; changes.txt indicates it
251 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>
252 <tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
256 <tr class="odd"><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
260 <tr><td><a href="http://www.postgresql.org/docs/8.4/static/libpq-threading.html">libpq (PostgreSQL)</a></td>
263 <td>Don't share connections across threads and watch out for
264 <code>crypt()</code> calls</td></tr>
265 <tr class="odd"><td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml">Sablotron</a></td>
269 <tr><td><a href="http://www.gzip.org/zlib/">zlib</a></td>
272 <td>Relies upon thread-safe zalloc and zfree functions Default is to
273 use libc's calloc/free which are thread-safe.</td></tr>
276 <div class="bottomlang">
277 <p><span>Available Languages: </span><a href="../en/developer/thread_safety.html" title="English"> en </a></p>
278 </div><div id="footer">
279 <p class="apache">Copyright 2009 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>
280 <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>