doc/rrdthreads.html

   1 <?xml version="1.0" ?>
   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">
   4 <head>
   5 <title>rrdthreads</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:root@localhost" />
   8 </head>
   9
  10 <body style="background-color: white">
  11
  12 <p><a name="__index__"></a></p>
  13 <!-- INDEX BEGIN -->
  14 <!--
  15
  16 <ul>
  17
  18         <li><a href="#name">NAME</a></li>
  19         <li><a href="#synopsis">SYNOPSIS</a></li>
  20         <li><a href="#description">DESCRIPTION</a></li>
  21         <ul>
  22
  23                 <li><a href="#notes_for_rrd_contributors">NOTES FOR RRD CONTRIBUTORS</a></li>
  24                 <li><a href="#currently_implemented_thread_safe_functions">CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS</a></li>
  25         </ul>
  26
  27         <li><a href="#author">AUTHOR</a></li>
  28 </ul>
  29 -->
  30 <!-- INDEX END -->
  31
  32 <p>
  33 </p>
  34 <h1><a name="name">NAME</a></h1>
  35 <p>rrdthreads - Provisions for linking the RRD library to use in multi-threaded programs</p>
  36 <p>
  37 </p>
  38 <hr />
  39 <h1><a name="synopsis">SYNOPSIS</a></h1>
  40 <p>Using librrd in multi-threaded programs requires some extra
  41 precautions, as the RRD library in its original form was not
  42 thread-safe at all. This document describes requirements and pitfalls
  43 on the way to use the multi-threaded version of librrd in your own
  44 programs. It also gives hints for future RRD development to keep the
  45 library thread-safe.</p>
  46 <p>Currently only some RRD operations are implemented in a thread-safe
  47 way. They all end in the usual ``<code>_r</code>'' suffix.</p>
  48 <p>
  49 </p>
  50 <hr />
  51 <h1><a name="description">DESCRIPTION</a></h1>
  52 <p>In order to use librrd in multi-threaded programs you must:</p>
  53 <ul>
  54 <li>
  55 <p>Link with <em>librrd_th</em> instead of <em>librrd</em> (use <code>-lrrd_th</code> when
  56 linking)</p>
  57 </li>
  58 <li>
  59 <p>Use the ``<code>_r</code>'' functions instead of the normal API-functions</p>
  60 </li>
  61 <li>
  62 <p>Do not use any at-style time specifications. Parsing of such time
  63 specifications is terribly non-thread-safe.</p>
  64 </li>
  65 <li>
  66 <p>Never use non *<code>_r</code> functions unless it is explicitly documented that
  67 the function is tread-safe.</p>
  68 </li>
  69 <li>
  70 <p>Every thread SHOULD call <code>rrd_get_context()</code> before its first call to
  71 any <code>librrd_th</code> function in order to set up thread specific data. This
  72 is not strictly required, but it is the only way to test if memory
  73 allocation can be done by this function. Otherwise the program may die
  74 with a SIGSEGV in a low-memory situation.</p>
  75 </li>
  76 <li>
  77 <p>Always call <code>rrd_error_clear()</code> before any call to the
  78 library. Otherwise the call might fail due to some earlier error.</p>
  79 </li>
  80 </ul>
  81 <p>
  82 </p>
  83 <h2><a name="notes_for_rrd_contributors">NOTES FOR RRD CONTRIBUTORS</a></h2>
  84 <p>Some precautions must be followed when developing RRD from now on:</p>
  85 <ul>
  86 <li>
  87 <p>Only use thread-safe functions in library code. Many often used libc
  88 functions aren't thread-safe. Take care in the following
  89 situations or when using the following library functions:</p>
  90 <ul>
  91 <li>
  92 <p>Direct calls to <code>strerror()</code> must be avoided: use <code>rrd_strerror()</code>
  93 instead, it provides a per-thread error message.</p>
  94 </li>
  95 <li>
  96 <p>The <code>getpw*</code>, <code>getgr*</code>, <code>gethost*</code> function families (and some more
  97 <code>get*</code> functions) are not thread-safe: use the *<code>_r</code> variants</p>
  98 </li>
  99 <li>
 100 <p>Time functions: <code>asctime</code>, <code>ctime</code>, <code>gmtime</code>, <code>localtime</code>: use
 101 *<code>_r</code> variants</p>
 102 </li>
 103 <li>
 104 <p><code>strtok</code>: use <code>strtok_r</code></p>
 105 </li>
 106 <li>
 107 <p><code>tmpnam</code>: use <code>tmpnam_r</code></p>
 108 </li>
 109 <li>
 110 <p>Many others (lookup documentation)</p>
 111 </li>
 112 </ul>
 113 </li>
 114 <li>
 115 <p>A header file named <em>rrd_is_thread_safe.h</em> is provided
 116 that works with the GNU C-preprocessor to ``poison'' some of the most
 117 common non-thread-safe functions using the <code>#pragma GCC poison</code>
 118 directive. Just include this header in source files you want to keep
 119 thread-safe.</p>
 120 </li>
 121 <li>
 122 <p>Do not introduce global variables!</p>
 123 <p>If you really, really have to use a global variable you may add a new
 124 field to the <code>rrd_context</code> structure and modify <em>rrd_error.c</em>,
 125 <em>rrd_thread_safe.c</em> and <em>rrd_non_thread_safe.c</em></p>
 126 </li>
 127 <li>
 128 <p>Do not use <code>getopt</code> or <code>getopt_long</code> in *<code>_r</code> (neither directly nor
 129 indirectly).</p>
 130 <p><code>getopt</code> uses global variables and behaves badly in a multi-threaded
 131 application when called concurrently. Instead provide a *_r function
 132 taking all options as function parameters. You may provide argc and
 133 **argv arguments for variable length argument lists. See
 134 <code>rrd_update_r</code> as an example.</p>
 135 </li>
 136 <li>
 137 <p>Do not use the <code>rrd_parsetime</code> function!</p>
 138 <p>It uses lots of global variables. You may use it in functions not designed
 139 to be thread-safe, like in functions wrapping the <code>_r</code> version of some
 140 operation (e.g., <code>rrd_create</code>, but not in <code>rrd_create_r</code>)</p>
 141 </li>
 142 </ul>
 143 <p>
 144 </p>
 145 <h2><a name="currently_implemented_thread_safe_functions">CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS</a></h2>
 146 <p>Currently there exist thread-safe variants of <code>rrd_update</code>,
 147 <code>rrd_create</code>, <code>rrd_dump</code>, <code>rrd_info</code>, <code>rrd_last</code>, and <code>rrd_fetch</code>.</p>
 148 <p>
 149 </p>
 150 <hr />
 151 <h1><a name="author">AUTHOR</a></h1>
 152 <p>Peter Stamfest &lt;<a href="mailto:peter@stamfest.at">peter@stamfest.at</a>&gt;</p>
 153
 154 </body>
 155
 156 </html>