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>" suffix.
  16
  17 =head1 DESCRIPTION
  18
  19 In order to use librrd in multi-threaded programs you must:
  20
  21 =over
  22
  23 =item *
  24
  25 Link with F<librrd_th> instead of F<librrd> (use C<-lrrd_th> when
  26 linking)
  27
  28 =item *
  29
  30 Use the "C<_r>" functions instead of 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 =head2 NOTES FOR RRD CONTRIBUTORS
  58
  59 Some precautions must be followed when developing RRD from now on:
  60
  61 =over
  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 or when using the following library functions:
  68
  69 =over
  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 others (lookup documentation)
  97
  98 =back
  99
 100 =item *
 101
 102 A header file named F<rrd_is_thread_safe.h> is provided
 103 that works with the GNU C-preprocessor to "poison" some of the most
 104 common non-thread-safe functions using the C<#pragma GCC poison>
 105 directive. Just include this header in source files you want to keep
 106 thread-safe.
 107
 108 =item *
 109
 110 Do not introduce global variables!
 111
 112 If you really, really have to use a global variable you may add a new
 113 field to the C<rrd_context> structure and modify F<rrd_error.c>,
 114 F<rrd_thread_safe.c> and F<rrd_non_thread_safe.c>
 115
 116 =item *
 117
 118 Do not use C<getopt> or C<getopt_long> in *C<_r> (neither directly nor
 119 indirectly).
 120
 121 C<getopt> uses global variables and behaves badly in a multi-threaded
 122 application when called concurrently. Instead provide a *_r function
 123 taking all options as function parameters. You may provide argc and
 124 **argv arguments for variable length argument lists. See
 125 C<rrd_update_r> as an example.
 126
 127 =item *
 128
 129 Do not use the C<rrd_parsetime> function!
 130
 131 It uses lots of global variables. You may use it in functions not designed
 132 to be thread-safe, like in functions wrapping the C<_r> version of some
 133 operation (e.g., C<rrd_create>, but not in C<rrd_create_r>)
 134
 135 =back
 136
 137 =head2 CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS
 138
 139 Currently there exist thread-safe variants of C<rrd_update>,
 140 C<rrd_create>, C<rrd_dump>, C<rrd_info>, C<rrd_last>, and C<rrd_fetch>.
 141
 142 =head1 AUTHOR
 143
 144 Peter Stamfest E<lt>peter@stamfest.atE<gt>