doc/rrdthreads.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "RRDTHREADS 1"
 132 .TH RRDTHREADS 1 "2008-06-08" "1.3.99909060808" "rrdtool"
 133 .SH "NAME"
 134 rrdthreads \- Provisions for linking the RRD library to use in multi\-threaded programs
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 Using librrd in multi-threaded programs requires some extra
 138 precautions, as the \s-1RRD\s0 library in its original form was not
 139 thread-safe at all. This document describes requirements and pitfalls
 140 on the way to use the multi-threaded version of librrd in your own
 141 programs. It also gives hints for future \s-1RRD\s0 development to keep the
 142 library thread\-safe.
 143 .PP
 144 Currently only some \s-1RRD\s0 operations are implemented in a thread-safe
 145 way. They all end in the usual "\f(CW\*(C`_r\*(C'\fR" suffix.
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 In order to use librrd in multi-threaded programs you must:
 149 .IP "\(bu" 4
 150 Link with \fIlibrrd_th\fR instead of \fIlibrrd\fR (use \f(CW\*(C`\-lrrd_th\*(C'\fR when
 151 linking)
 152 .IP "\(bu" 4
 153 Use the "\f(CW\*(C`_r\*(C'\fR" functions instead of the normal API-functions
 154 .IP "\(bu" 4
 155 Do not use any at-style time specifications. Parsing of such time
 156 specifications is terribly non\-thread\-safe.
 157 .IP "\(bu" 4
 158 Never use non *\f(CW\*(C`_r\*(C'\fR functions unless it is explicitly documented that
 159 the function is tread\-safe.
 160 .IP "\(bu" 4
 161 Every thread \s-1SHOULD\s0 call \f(CW\*(C`rrd_get_context()\*(C'\fR before its first call to
 162 any \f(CW\*(C`librrd_th\*(C'\fR function in order to set up thread specific data. This
 163 is not strictly required, but it is the only way to test if memory
 164 allocation can be done by this function. Otherwise the program may die
 165 with a \s-1SIGSEGV\s0 in a low-memory situation.
 166 .IP "\(bu" 4
 167 Always call \f(CW\*(C`rrd_error_clear()\*(C'\fR before any call to the
 168 library. Otherwise the call might fail due to some earlier error.
 169 .Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1RRD\s0 \s-1CONTRIBUTORS\s0"
 170 .IX Subsection "NOTES FOR RRD CONTRIBUTORS"
 171 Some precautions must be followed when developing \s-1RRD\s0 from now on:
 172 .IP "\(bu" 4
 173 Only use thread-safe functions in library code. Many often used libc
 174 functions aren't thread\-safe. Take care in the following
 175 situations or when using the following library functions:
 176 .RS 4
 177 .IP "\(bu" 4
 178 Direct calls to \f(CW\*(C`strerror()\*(C'\fR must be avoided: use \f(CW\*(C`rrd_strerror()\*(C'\fR
 179 instead, it provides a per-thread error message.
 180 .IP "\(bu" 4
 181 The \f(CW\*(C`getpw*\*(C'\fR, \f(CW\*(C`getgr*\*(C'\fR, \f(CW\*(C`gethost*\*(C'\fR function families (and some more
 182 \&\f(CW\*(C`get*\*(C'\fR functions) are not thread\-safe: use the *\f(CW\*(C`_r\*(C'\fR variants
 183 .IP "\(bu" 4
 184 Time functions: \f(CW\*(C`asctime\*(C'\fR, \f(CW\*(C`ctime\*(C'\fR, \f(CW\*(C`gmtime\*(C'\fR, \f(CW\*(C`localtime\*(C'\fR: use
 185 *\f(CW\*(C`_r\*(C'\fR variants
 186 .IP "\(bu" 4
 187 \&\f(CW\*(C`strtok\*(C'\fR: use \f(CW\*(C`strtok_r\*(C'\fR
 188 .IP "\(bu" 4
 189 \&\f(CW\*(C`tmpnam\*(C'\fR: use \f(CW\*(C`tmpnam_r\*(C'\fR
 190 .IP "\(bu" 4
 191 Many others (lookup documentation)
 192 .RE
 193 .RS 4
 194 .RE
 195 .IP "\(bu" 4
 196 A header file named \fIrrd_is_thread_safe.h\fR is provided
 197 that works with the \s-1GNU\s0 C\-preprocessor to \*(L"poison\*(R" some of the most
 198 common non-thread-safe functions using the \f(CW\*(C`#pragma GCC poison\*(C'\fR
 199 directive. Just include this header in source files you want to keep
 200 thread\-safe.
 201 .IP "\(bu" 4
 202 Do not introduce global variables!
 203 .Sp
 204 If you really, really have to use a global variable you may add a new
 205 field to the \f(CW\*(C`rrd_context\*(C'\fR structure and modify \fIrrd_error.c\fR,
 206 \&\fIrrd_thread_safe.c\fR and \fIrrd_non_thread_safe.c\fR
 207 .IP "\(bu" 4
 208 Do not use \f(CW\*(C`getopt\*(C'\fR or \f(CW\*(C`getopt_long\*(C'\fR in *\f(CW\*(C`_r\*(C'\fR (neither directly nor
 209 indirectly).
 210 .Sp
 211 \&\f(CW\*(C`getopt\*(C'\fR uses global variables and behaves badly in a multi-threaded
 212 application when called concurrently. Instead provide a *_r function
 213 taking all options as function parameters. You may provide argc and
 214 **argv arguments for variable length argument lists. See
 215 \&\f(CW\*(C`rrd_update_r\*(C'\fR as an example.
 216 .IP "\(bu" 4
 217 Do not use the \f(CW\*(C`rrd_parsetime\*(C'\fR function!
 218 .Sp
 219 It uses lots of global variables. You may use it in functions not designed
 220 to be thread\-safe, like in functions wrapping the \f(CW\*(C`_r\*(C'\fR version of some
 221 operation (e.g., \f(CW\*(C`rrd_create\*(C'\fR, but not in \f(CW\*(C`rrd_create_r\*(C'\fR)
 222 .Sh "\s-1CURRENTLY\s0 \s-1IMPLEMENTED\s0 \s-1THREAD\s0 \s-1SAFE\s0 \s-1FUNCTIONS\s0"
 223 .IX Subsection "CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS"
 224 Currently there exist thread-safe variants of \f(CW\*(C`rrd_update\*(C'\fR,
 225 \&\f(CW\*(C`rrd_create\*(C'\fR, \f(CW\*(C`rrd_dump\*(C'\fR, \f(CW\*(C`rrd_info\*(C'\fR, \f(CW\*(C`rrd_last\*(C'\fR, and \f(CW\*(C`rrd_fetch\*(C'\fR.
 226 .SH "AUTHOR"
 227 .IX Header "AUTHOR"
 228 Peter Stamfest <peter@stamfest.at>