home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F277798_thread_safety.xml < prev    next >
Extensible Markup Language  |  2004-04-17  |  14KB  |  291 lines
  1. <?xml version="1.0" encoding="UTF-8" ?>
  2. <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <!-- $Revision: 1.1.2.8 $ -->
  5.  
  6. <!--
  7.  Copyright 2003-2004 The Apache Software Foundation
  8.  
  9.  Licensed under the Apache License, Version 2.0 (the "License");
  10.  you may not use this file except in compliance with the License.
  11.  You may obtain a copy of the License at
  12.  
  13.      http://www.apache.org/licenses/LICENSE-2.0
  14.  
  15.  Unless required by applicable law or agreed to in writing, software
  16.  distributed under the License is distributed on an "AS IS" BASIS,
  17.  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18.  See the License for the specific language governing permissions and
  19.  limitations under the License.
  20. -->
  21.  
  22. <manualpage metafile="thread_safety.xml.meta">
  23. <parentdocument href="./">Developer Documentation</parentdocument>
  24.  
  25. <title>Apache 2.0 Thread Safety Issues</title>
  26.  
  27. <summary>
  28.     <p>When using any of the threaded mpms in Apache 2.0 it is important
  29.     that every function called from Apache be thread safe.  When linking in 3rd
  30.     party extensions it can be difficult to determine whether the resulting
  31.     server will be thread safe.  Casual testing generally won't tell you this
  32.     either as thread safety problems can lead to subtle race conditons that
  33.     may only show up in certain conditions under heavy load.</p>
  34. </summary>
  35.  
  36. <section id="variables"><title>Global and static variables</title>
  37.     <p>When writing your module or when trying to determine if a module or
  38.     3rd party library is thread safe there are some common things to keep in
  39.     mind.</p>
  40.  
  41.     <p>First, you need to recognize that in a threaded model each individual
  42.     thread has its own program counter, stack and registers.  Local variables
  43.     live on the stack, so those are fine.  You need to watch out for any
  44.     static or global variables.  This doesn't mean that you are absolutely not
  45.     allowed to use static or global variables.  There are times when you
  46.     actually want something to affect all threads, but generally you need to
  47.     avoid using them if you want your code to be thread safe.</p>
  48.    
  49.     <p>In the case where you have a global variable that needs to be global and
  50.     accessed by all threads, be very careful when you update it.  If, for
  51.     example, it is an incrementing counter, you need to atomically increment
  52.     it to avoid race conditions with other threads.  You do this using a mutex
  53.     (mutual exclusion). Lock the mutex, read the current value, increment it
  54.     and write it back and then unlock the mutex.  Any other thread that wants
  55.     to modify the value has to first check the mutex and block until it is
  56.     cleared.</p>
  57.  
  58.     <p>If you are using <a href="http://apr.apache.org/">APR</a>, have a look
  59.     at the <code>apr_atomic_<var>*</var></code> functions and the
  60.     <code>apr_thread_mutex_<var>*</var></code> functions.</p>
  61.     <!-- [would probably be a good idea to add an example here] -->
  62. </section>
  63.  
  64. <section id="errno"><title>errno</title>
  65.     <p>This is a common global variable that holds the error number of the
  66.     last error that occurred. If one thread calls a low-level function that
  67.     sets errno and then another thread checks it, we are bleeding error
  68.     numbers from one thread into another.  To solve this, make sure your
  69.     module or library defines <code>_REENTRANT</code> or is compiled with
  70.     <code>-D_REENTRANT</code>. This will make errno a per-thread variable
  71.     and should hopefully be transparent to the code. It does this by doing
  72.     something like this:</p>
  73.  
  74.     <example>
  75.       #define errno (*(__errno_location()))
  76.     </example>
  77.  
  78.     <p>which means that accessing errno will call
  79.     <code>__errno_location()</code> which is provided by the libc. Setting
  80.     <code>_REENTRANT</code> also forces redefinition of some other functions
  81.     to their <code><var>*</var>_r</code> equivalents and sometimes changes
  82.     the common <code>getc</code>/<code>putc</code> macros into safer function
  83.     calls.  Check your libc documentation for specifics.  Instead of, or in
  84.     addition to <code>_REENTRANT</code> the symbols that may affect this are 
  85.     <code>_POSIX_C_SOURCE</code>, <code>_THREAD_SAFE</code>,
  86.     <code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
  87. </section>
  88.  
  89. <section id="functions"><title>Common standard troublesome functions</title>
  90.     <p>Not only do things have to be thread safe, but they also have to be
  91.     reentrant. <code>strtok()</code> is an obvious one. You call it the first
  92.     time with your delimiter which it then remembers and on each subsequent
  93.     call it returns the next token.  Obviously if multiple threads are
  94.     calling it you will have a problem.  Most systems have a reentrant version
  95.     of of the function called <code>strtok_r()</code> where you pass in an
  96.     extra argument which contains an allocated <code>char *</code> which the
  97.     function will use instead of its own static storage for maintaining
  98.     the tokenizing state. If you are using <a href="http://apr.apache.org/"
  99.     >APR</a> you can use <code>apr_strtok()</code>.</p>
  100.  
  101.     <p><code>crypt()</code> is another function that tends to not be reentrant,
  102.     so if you run across calls to that function in a library, watch out. On
  103.     some systems it is reentrant though, so it is not always a problem. If
  104.     your system has <code>crypt_r()</code> chances are you should be using
  105.     that, or if possible simply avoid the whole mess by using md5 instead.</p>
  106.     <!-- [I don't see an apr_crypt() function.] -->
  107. </section>
  108.  
  109. <section id="commonlibs"><title>Common 3rd Party Libraries</title>
  110.     <p>The following is a list of common libraries that are used by 3rd party
  111.     Apache modules.  You can check to see if your module is using a potentially
  112.     unsafe library by using tools such as <code>ldd(1)</code> and
  113.     <code>nm(1)</code>. For <a href="http://www.php.net/">PHP</a>, for example,
  114.     try this:</p>
  115.  
  116.     <example>
  117.       % ldd libphp4.so<br />
  118.       libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)<br />
  119.       libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)<br />
  120.       libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)<br />
  121.       libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)<br />
  122.       libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)<br />
  123.       libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)<br />
  124.       libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)<br />
  125.       libming.so => /usr/lib/libming.so (0x40449000)<br />
  126.       libm.so.6 => /lib/libm.so.6 (0x40487000)<br />
  127.       libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)<br />
  128.       libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)<br />
  129.       libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)<br />
  130.       libssl.so.2 => /lib/libssl.so.2 (0x40532000)<br />
  131.       libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)<br />
  132.       libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)<br />
  133.       libdl.so.2 => /lib/libdl.so.2 (0x40634000)<br />
  134.       libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)<br />
  135.       libc.so.6 => /lib/libc.so.6 (0x4064b000)<br />
  136.       /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)
  137.     </example>
  138.  
  139.     <p>In addition to these libraries you will need to have a look at any
  140.     libraries linked statically into the module. You can use <code>nm(1)</code>
  141.     to look for individual symbols in the module.</p>
  142. </section>
  143.  
  144. <section id="liblist"><title>Library List</title>
  145.     <p>Please drop a note to <a
  146.     href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a>
  147.     if you have additions or corrections to this list.</p>
  148.  
  149.     <table style="zebra" border="1">
  150.     <tr><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>
  152.         <td> </td>
  153.         <td>?</td>
  154.         <td> </td></tr>
  155.     <tr><td><a href="http://www.sleepycat.com/">Berkeley DB</a></td>
  156.         <td>3.x, 4.x</td>
  157.         <td>Yes</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>
  160.         <td> </td>
  161.         <td>Yes</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><td><a href="http://cr.yp.to/cdb.html">cdb</a></td>
  165.         <td> </td>
  166.         <td>?</td>
  167.         <td> </td></tr>
  168.     <tr><td><a href="http://www.washington.edu/imap/">C-Client</a></td>
  169.         <td> </td>
  170.         <td>Perhaps</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><td><a href="http://www.fastio.com/">cpdflib</a></td>
  178.         <td> </td>
  179.         <td>?</td>
  180.         <td> </td></tr>
  181.     <tr><td><a href="http://www.ijg.org/files/">libcrypt</a></td>
  182.         <td> </td>
  183.         <td>?</td>
  184.         <td> </td></tr>
  185.     <tr><td><a href="http://expat.sourceforge.net/">Expat</a></td>
  186.         <td> </td>
  187.         <td>Yes</td>
  188.         <td>Need a separate parser instance per thread</td></tr>
  189.     <tr><td><a href="http://www.freetds.org/">FreeTDS</a></td>
  190.         <td> </td>
  191.         <td>?</td>
  192.         <td> </td></tr>
  193.     <tr><td><a href="http://www.freetype.org/">FreeType</a></td>
  194.         <td> </td>
  195.         <td>?</td>
  196.         <td> </td></tr>
  197.     <tr><td><a href="http://www.boutell.com/gd/">GD 1.8.x</a></td>
  198.         <td> </td>
  199.         <td>?</td>
  200.         <td> </td></tr>
  201.     <tr><td><a href="http://www.boutell.com/gd/">GD 2.0.x</a></td>
  202.         <td> </td>
  203.         <td>?</td>
  204.         <td> </td></tr>
  205.     <tr><td><a href="http://www.gnu.org/software/gdbm/gdbm.html">gdbm</a></td>
  206.         <td> </td>
  207.         <td>No</td>
  208.         <td>Errors returned via a static <code>gdbm_error</code>
  209.         variable</td></tr>
  210.     <tr><td><a href="http://www.imagemagick.org/">ImageMagick</a></td>
  211.         <td>5.2.2</td>
  212.         <td>Yes</td>
  213.         <td>ImageMagick docs claim it is thread safe since version 5.2.2 (see <a
  214.         href="http://www.cise.ufl.edu/depot/www/ImageMagick/www/Changelog.html"
  215.         >Change log</a>).
  216.         </td></tr>
  217.     <tr><td><a href="http://www.enlightenment.org/pages/imlib2.html"
  218.         >Imlib2</a></td>
  219.         <td> </td>
  220.         <td>?</td>
  221.         <td> </td></tr>
  222.     <tr><td><a href="http://www.ijg.org/files/">libjpeg</a></td>
  223.         <td>v6b</td>
  224.         <td>?</td>
  225.         <td> </td></tr>
  226.     <tr><td><a href="http://mysql.com">libmysqlclient</a></td>
  227.         <td> </td>
  228.         <td>Yes</td>
  229.         <td>Use mysqlclient_r library variant to ensure thread-safety.  For
  230.             more information, please read <a
  231.             href="http://www.mysql.com/doc/en/Threaded_clients.html"
  232.             >http://www.mysql.com/doc/en/Threaded_clients.html</a>.</td></tr>
  233.     <tr><td><a href="http://www.opaque.net/ming/">Ming</a></td>
  234.         <td>0.2a</td>
  235.         <td>?</td>
  236.         <td> </td></tr>
  237.     <tr><td><a href="http://net-snmp.sourceforge.net/">Net-SNMP</a></td>
  238.         <td>5.0.x</td>
  239.         <td>?</td>
  240.         <td> </td></tr>
  241.     <tr><td><a href="http://www.openldap.org/">OpenLDAP</a></td>
  242.         <td>2.1.x</td>
  243.         <td>Yes</td>
  244.         <td>Use <code>ldap_r</code> library variant to ensure
  245.         thread-safety.</td></tr>
  246.     <tr><td><a href="http://www.openssl.org/">OpenSSL</a></td>
  247.         <td>0.9.6g</td>
  248.         <td>Yes</td>
  249.         <td>Requires proper usage of <code>CRYPTO_num_locks</code>,
  250.         <code>CRYPTO_set_locking_callback</code>,
  251.         <code>CRYPTO_set_id_callback</code></td></tr>
  252.     <tr><td><a href="http://www.oracle.com/">liboci8 (Oracle 8+)</a></td>
  253.         <td>8.x,9.x</td>
  254.         <td>?</td>
  255.         <td> </td></tr>
  256.     <tr><td><a href="http://pdflib.com/">pdflib</a></td>
  257.         <td>5.0.x</td>
  258.         <td>Yes</td>
  259.         <td>PDFLib docs claim it is thread safe; changes.txt indicates it
  260.             has been partially thread-safe since V1.91: <a
  261.             href="http://www.pdflib.com/products/pdflib/index.html"
  262.             >http://www.pdflib.com/products/pdflib/index.html</a>.</td></tr>
  263.     <tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
  264.         <td>1.0.x</td>
  265.         <td>?</td>
  266.         <td> </td></tr>
  267.     <tr><td><a href="http://www.libpng.org/pub/png/libpng.html">libpng</a></td>
  268.         <td>1.2.x</td>
  269.         <td>?</td>
  270.         <td> </td></tr>
  271.     <tr><td><a
  272.         href="http://www.postgresql.org/idocs/index.php?libpq-threading.html"
  273.         >libpq (PostgreSQL)</a></td>
  274.         <td>7.x</td>
  275.         <td>Yes</td>
  276.         <td>Don't share connections across threads and watch out for
  277.         <code>crypt()</code> calls</td></tr>
  278.     <tr><td><a href="http://www.gingerall.com/charlie/ga/xml/p_sab.xml"
  279.         >Sablotron</a></td>
  280.         <td>0.95</td>
  281.         <td>?</td>
  282.         <td></td></tr>
  283.     <tr><td><a href="http://www.gzip.org/zlib/">zlib</a></td>
  284.         <td>1.1.4</td>
  285.         <td>Yes</td>
  286.         <td>Relies upon thread-safe zalloc and zfree functions  Default is to
  287.         use libc's calloc/free which are thread-safe.</td></tr>
  288.     </table>
  289. </section>
  290. </manualpage>
  291.