98N/A<!
DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 919N/A <
title>Apache 2.0 Thread Safety Issues</
title>
919N/A <!-- Background white, links blue (unvisited), navy (visited), red (active) --> 919N/A <
body bgcolor="#FFFFFF" text="#000000" link="#0000FF" 919N/A vlink="#000080" alink="#FF0000">
919N/A <
p>When using any of the threaded mpms in Apache 2.0 it is important
919N/A that every function called from Apache be thread safe. When linking in 3rd
919N/A party extensions it can be difficult to determine whether the resulting
919N/A server will be thread safe. Casual testing generally won't tell you this
919N/A either as thread safety problems can lead to subtle race conditons that
919N/A may only show up in certain conditions under heavy load.</
p>
98N/A <
h2>Global and static variables</
h2>
98N/A <
p>When writing your module or when trying to determine if a module or
493N/A 3rd party library is thread safe there are some common things to keep in mind.
98N/A First, you need to recognize that in a threaded model each individual thread
1339N/A has its own program counter, stack and registers. Local variables live on the
1339N/A stack, so those are fine. You need to watch out for any static or global
1339N/A variables. This doesn't mean that you are absolutely not allowed to use static
98N/A or global variables. There are times when you actually want something to affect
1301N/A all threads, but generally you need to avoid using them if you want your code to
98N/A be thread safe.</
p>
1301N/A <
p>In the case where you have a global variable that needs to be global and
1301N/A accessed by all threads, be very careful when you update it. If, for example,
1301N/A it is an incrementing counter, you need to atomically increment it to avoid
911N/A race conditions with other threads. You do this using a mutex (mutual exclusion).
98N/A Lock the mutex, read the current value, increment it and write it back and then unlock
1276N/A the mutex. Any other thread that wants to modify the value has to first check the mutex
98N/A and block until it is cleared.</
p>
1003N/A <
p>If you are using APR, have a look at the apr_atomic_* functions and the apr_thread_mutex_*
1056N/A functions. [would probably be a good idea to add an example here]</
p>
493N/A <
p>This is a common global variable that holds the error number of the last error that occurred.
1056N/A If one thread calls a low-level function that sets errno and then another thread checks it, we
479N/A are bleeding error numbers from one thread into another. To solve this, make sure your module
98N/A or library defines _REENTRANT or is compiled with -D_REENTRANT. This will make errno a per-thread
1056N/A variable and should hopefully be transparent to the code. It does this by doing something like this:</
p>
493N/A<
pre>#define errno (*(__errno_location()))</
pre>
910N/A <
p>which means that accessing errno will call __errno_location() which is provided by the libc. Setting
910N/A _REENTRANT also forces redefinition of some other functions to their *_r equivalents and sometimes
98N/A changes the common
getc/
putc macros into safer function calls. Check your libc documentation for
98N/A specifics. Instead of, or in addition to _REENTRANT the symbols that may affect this are
98N/A _POSIX_C_SOURCE, _THREAD_SAFE, _SVID_SOURCE, and _BSD_SOURCE.</
p>
1056N/A <
h2>Common standard troublesome functions</
h2>
1056N/A <
p>Not only do things have to be thread safe, but they also have to be reentrant.
1056N/A <
b>strtok()</
b> is an obvious one. You call it the first time with your delimiter which
479N/A it then remembers and on each subsequent call it returns the next token. Obviously if
98N/A multiple threads are calling it you will have a problem. Most systems have a reentrant version
963N/A of of the function called <
b>strtok_r()</
b> where you pass in an extra argument which contains
963N/A an allocated char * which the function will use instead of its own static storage for maintaining
963N/A the tokenizing state. If you are using APR you can use <
b>apr_strtok()</
b>.</
p>
963N/A <
p><
b>crypt()</
b> is another function that tends to not be reentrant, so if you run across calls
963N/A to that function in a library, watch out. On some systems it is reentrant though, so it is not
935N/A always a problem. If your system has <
b>crypt_r()</
b> chances are you should be using that, or
963N/A if possible simply avoid the whole mess by using md5 instead. [I don't see an apr_crypt() function.]</
p>
1056N/A <
h1>Common 3rd Party Libraries</
h1>
1056N/A <
p>The following is a list of common libraries that are used by 3rd party
1056N/A Apache modules. You can check to see if your module is using a potentially
1056N/A unsafe library by using tools such as <
tt>ldd</
tt> and <
tt>nm</
tt>. For
1056N/A PHP, for example, try this:</
p>
<
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>
<
p>Please drop a note to dev@httpd.apache.org if you have additions or
corrections to this list.</
p>
<
td>Be careful about sharing a connection across threads.</
td>
<
td>Both low-level and high-level APIs are thread-safe. However, high-level API requires thread-safe access to errno.</
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>
<
td>Need a separate parser instance per thread</
td>
<
td>Errors returned via a static gdbm_error variable</
td>
<
td>ImageMagick docs claim it is thread safe since version 5.2.2
<
td>Use mysqlclient_r library variant to ensure thread-safety. For
more information, please read <
a <
td>Use ldap_r library variant to ensure thread-safety.</
td>
<
td>Requires proper usage of <
i>CRYPTO_num_locks</
i>, <
i>CRYPTO_set_locking_callback</
i>, <
i>CRYPTO_set_id_callback</
i></
td>
<
td>PDFLib docs claim it is thread safe;
changes.txt indicates it
has been partially thread-safe since V1.91: <
a <
td>Don't share connections across threads and watch out for crypt() calls</
td>
<
td>Relies upon thread-safe zalloc and zfree functions. Default is to use libc's
calloc/
free which are thread-safe.</
td>