program/doc/rrdthreads.pod

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