Code

patches/bts498183-segfault-madvise: Removed unnecessary whitespace changes.
[pkg-rrdtool.git] / doc / rrdthreads.1
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
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.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
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.1" "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>