Google Git
Sign in
apache / httpd / 4703b66bc2b2b40d09675077870235e925d653f9 / . / docs / manual / developer / thread_safety.html
blob: ad6e73c0e4fb52f907a7e0931e81ec34960cfa8a [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<title>Apache 2.0 Thread Safety Issues</title>
</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
vlink="#000080" alink="#FF0000">
<!--#include virtual="header.html" -->
<h1>Thread Safety</h1>
<p>When using any of the threaded mpms in Apache 2.0 it is important
that every function called from Apache be thread safe. When linking in 3rd
party extensions it can be difficult to determine whether the resulting
server will be thread safe. Casual testing generally won't tell you this
either as thread safety problems can lead to subtle race conditons that
may only show up in certain conditions under heavy load.</p>
<h2>Global and static variables</h2>
<p>When writing your module or when trying to determine if a module or
3rd party library is thread safe there are some common things to keep in mind.
First, you need to recognize that in a threaded model each individual thread
has its own program counter, stack and registers. Local variables live on the
stack, so those are fine. You need to watch out for any static or global
variables. This doesn't mean that you are absolutely not allowed to use static
or global variables. There are times when you actually want something to affect
all threads, but generally you need to avoid using them if you want your code to
be thread safe.</p>
<p>In the case where you have a global variable that needs to be global and
accessed by all threads, be very careful when you update it. If, for example,
it is an incrementing counter, you need to atomically increment it to avoid
race conditions with other threads. You do this using a mutex (mutual exclusion).
Lock the mutex, read the current value, increment it and write it back and then unlock
the mutex. Any other thread that wants to modify the value has to first check the mutex
and block until it is cleared.</p>
<p>If you are using APR, have a look at the apr_atomic_* functions and the apr_thread_mutex_*
functions. [would probably be a good idea to add an example here]</p>
<h2>errno</h2>
<p>This is a common global variable that holds the error number of the last error that occurred.
If one thread calls a low-level function that sets errno and then another thread checks it, we
are bleeding error numbers from one thread into another. To solve this, make sure your module
or library defines _REENTRANT or is compiled with -D_REENTRANT. This will make errno a per-thread
variable and should hopefully be transparent to the code. It does this by doing something like this:</p>
<pre>#define errno (*(__errno_location()))</pre>
<p>which means that accessing errno will call __errno_location() which is provided by the libc. Setting
_REENTRANT also forces redefinition of some other functions to their *_r equivalents and sometimes
changes the common getc/putc macros into safer function calls. Check your libc documentation for
specifics. Instead of, or in addition to _REENTRANT the symbols that may affect this are
_POSIX_C_SOURCE, _THREAD_SAFE, _SVID_SOURCE, and _BSD_SOURCE.</p>
<h2>Common standard troublesome functions</h2>
<p>Not only do things have to be thread safe, but they also have to be reentrant.
<b>strtok()</b> is an obvious one. You call it the first time with your delimiter which
it then remembers and on each subsequent call it returns the next token. Obviously if
multiple threads are calling it you will have a problem. Most systems have a reentrant version
of of the function called <b>strtok_r()</b> where you pass in an extra argument which contains
an allocated char * which the function will use instead of its own static storage for maintaining
the tokenizing state. If you are using APR you can use <b>apr_strtok()</b>.</p>
<p><b>crypt()</b> is another function that tends to not be reentrant, so if you run across calls
to that function in a library, watch out. On some systems it is reentrant though, so it is not
always a problem. If your system has <b>crypt_r()</b> chances are you should be using that, or
if possible simply avoid the whole mess by using md5 instead. [I don't see an apr_crypt() function.]</p>
<h1>Common 3rd Party Libraries</h1>
<p>The following is a list of common libraries that are used by 3rd party
Apache modules. You can check to see if your module is using a potentially
unsafe library by using tools such as <tt>ldd</tt> and <tt>nm</tt>. For
PHP, for example, try this:</p>
<pre>% ldd libphp4.so
libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)
libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)
libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)
libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)
libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)
libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)
libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)
libming.so => /usr/lib/libming.so (0x40449000)
libm.so.6 => /lib/libm.so.6 (0x40487000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)
libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)
libssl.so.2 => /lib/libssl.so.2 (0x40532000)
libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)
libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)
libdl.so.2 => /lib/libdl.so.2 (0x40634000)
libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)
libc.so.6 => /lib/libc.so.6 (0x4064b000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)</pre>
<p>In addition to these libraries you will need to have a look at any libraries
linked statically into the module. You can use <tt>nm</tt> to look for
individual symbols in the module.</p>
<h2>Library List</h2>
<p>Please drop a note to dev@httpd.apache.org if you have additions or
corrections to this list.</p>
<table>
<tr>
<th>Library</th>
<th>Version</th>
<th>Thread Safe?</th>
<th>Notes</th>
</tr>
<tr>
<td><a href="http://aspell.sourceforge.net/">ASpell/PSpell</a></td>
<td></td>
<td>?</td>
<td></td>
</tr>
<tr>
<td><a href="http://www.sleepycat.com/">Berkeley DB</a></td>
<td>3.x, 4.x</td>
<td>Yes</td>
<td>Be careful about sharing a connection across threads.</td>
</tr>
<tr>
<td><a href="http://sources.redhat.com/bzip2/index.html">bzip2</a></td>
<td></td>
<td>Yes</td>
<td>Both low-level and high-level APIs are thread-safe. However, high-level API requires thread-safe access to errno.</td>
</tr>
<tr>
<td><a href="http://cr.yp.to/cdb.html">cdb</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.washington.edu/imap/">C-Client</a></td>
<td> </td>
<td>Perhaps</td>
<td>c-client uses strtok() and gethostbyname() which are not thread-safe on most C library implementations. c-client's static data is meant to be shared across threads. If strtok() and gethostbyname() are thread-safe on your OS, c-client <i>may</i> be thread-safe.</td>
</tr>
<tr>
<td><a href="http://www.fastio.com/">cpdflib</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.ijg.org/files/">libcrypt</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://expat.sourceforge.net/">Expat</a></td>
<td></td>
<td>Yes</td>
<td>Need a separate parser instance per thread</td>
</tr>
<tr>
<td><a href="http://www.freetds.org/">FreeTDS</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.freetype.org/">FreeType</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td>
<td> </td>
<td>No</td>
<td>Errors returned via a static gdbm_error variable</td>
</tr>
<tr>
<td><a href="http://www.imagemagick.org/">ImageMagick</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.enlightenment.org/pages/imlib2.html">Imlib2</a></td>
<td> </td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.ijg.org/files/">libjpeg</a></td>
<td>v6b</td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://mysql.com">libmysqlclient</a></td>
<td> </td>
<td>Yes</td>
<td>Use mysqlclient_r library variant to ensure thread-safety. For
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>
<tr>
<td><a href="http://www.opaque.net/ming/">Ming</a></td>
<td>0.2a</td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td>
<td>5.0.x</td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.openldap.org/">OpenLDAP</a></td>
<td>2.1.x</td>
<td>Yes</td>
<td>Use ldap_r library variant to ensure thread-safety.</td>
</tr>
<tr>
<td><a href="http://www.openssl.org/">OpenSSL</a></td>
<td>0.96g</td>
<td>Yes</td>
<td>Requires proper usage of <i>CRYPTO_num_locks</i>, <i>CRYPTO_set_locking_callback</i>, <i>CRYPTO_set_id_callback</i></td>
</tr>
<tr>
<td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td>
<td>8.x,9.x</td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://pdflib.com/">pdflib</a></td>
<td>4.0.x</td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
<td>1.0.x</td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
<td>1.2.x</td>
<td>?</td>
<td> </td>
</tr>
<tr>
<td><a href="http://www.postgresql.org/idocs/index.php?libpq-threading.html">libpq (PostgreSQL)</a></td>
<td>7.x</td>
<td>Yes</td>
<td>Don't share connections across threads and watch out for crypt() calls</td>
</tr>
<tr>
<td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml">Sablotron</a></td>
<td>0.95</td>
<td>?</td>
<td></td>
</tr>
<tr>
<td><a href="http://www.gzip.org/zlib/">zlib</a></td>
<td>1.1.4</td>
<td>Yes</td>
<td>Relies upon thread-safe zalloc and zfree functions. Default is to use libc's calloc/free which are thread-safe.</td>
</tr>
</table>
<!--#include virtual="footer.html" -->
</body>
</html>