program/THREADS

   1 In order to use the librrd in multi-threaded programs you must:
   2
   3   * Link with librrd_th instead of with librrd
   4   * Use the *_r function instead or the *-functions
   5   * Never use non *_r functions unless it is explicitly documented that the
   6     function is tread-safe
   7
   8 Every thread SHOULD call rrd_get_context() before the first call to
   9 any librrd function in order to set up thread specific data. This is
  10 not strictly required, but it is the only way to test if memory
  11 allocation can be done by this function. Otherwise the program may die
  12 with a SIGSEGV in a low-memory situation.
  13
  14
  15 IMPORTANT NOTE FOR RRD CONTRIBUTORS:
  16
  17 Some precautions must be followed when developing rrd from now on:
  18
  19 * Only use thread-safe functions in library code. Many often used libc
  20   functions aren't thread-safe. Take care if you want to use any of
  21   the following functions:
  22
  23     + direct strerror calls must be avoided: use rrd_strerror instead,
  24       it provides a per-thread error message
  25     + the getpw*, getgr*, gethost* function families (and some more get*
  26       functions): use the *_r variants
  27     + Time functions: asctime, ctime, gmtime, localtime: use *_r variants
  28     + strtok: use strtok_r
  29     + tmpnam: use tmpnam_r
  30     + many other (lookup documentation)
  31
  32 As an aide(?) a header file named "rrd_is_thread_safe.h" is provided
  33 that works with the GNU C-preprocessor to "poison" some of the most
  34 common non-thread-safe functions using the "#pragma GCC poison"
  35 directive. Just include this header in source files you want to keep
  36 thread-safe.
  37
  38 * Do not introduce global variables!
  39
  40   If you really, really have to use a global variable you may add a
  41   new field to the rrd_context structure and modify rrd_error.c,
  42   rrd_thread_safe.c and rrd_non_thread_safe.c
  43
  44 * Do not use "getopt" or "getopt_long" in *_r (directly or indirectly)
  45
  46   getopt uses global variables and behaves badly in a multithreaded
  47   application when called concurrently. Instead provide a *_r function
  48   taking all options as function parameters. You may provide argc and
  49   **argv arguments for variable length argument lists. See
  50   rrd_update_r as an example.
  51
  52 * Do not use the parsetime function!
  53
  54   It uses lots of global vars. You may use it in functions not
  55   designed to be thread-safe like functions wrapping the _r version of some
  56   operation (eg. rrd_create, but not in rrd_create_r)
  57
  58 WIN32 Platform Note (added 04/01/03):
  59
  60 Both rrdtool.vcproj (MSVC++ 7.0) and rrd.dsw (MSVC++ 6.0) are configured to compile with rrd_thread_safe_nt.c.