![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdthreads.1 b/doc/rrdthreads.1
index 4d846c6d74b91c6cc2e62c70a9564941bc1abe52..dbbe8e533bae2fd06419939df188f5d1c943cc3a 100644 (file)
--- a/doc/rrdthreads.1
+++ b/doc/rrdthreads.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. | will give a
-.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "RRDTHREADS 1"
-.TH RRDTHREADS 1 "2008-06-08" "1.3.99909060808" "rrdtool"
+.TH RRDTHREADS 1 "2009-04-19" "1.3.999" "rrdtool"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
.SH "NAME"
rrdthreads \- Provisions for linking the RRD library to use in multi\-threaded programs
.SH "SYNOPSIS"
thread-safe at all. This document describes requirements and pitfalls
on the way to use the multi-threaded version of librrd in your own
programs. It also gives hints for future \s-1RRD\s0 development to keep the
-library thread\-safe.
+library thread-safe.
.PP
Currently only some \s-1RRD\s0 operations are implemented in a thread-safe
way. They all end in the usual "\f(CW\*(C`_r\*(C'\fR" suffix.
Use the "\f(CW\*(C`_r\*(C'\fR" functions instead of the normal API-functions
.IP "\(bu" 4
Do not use any at-style time specifications. Parsing of such time
-specifications is terribly non\-thread\-safe.
+specifications is terribly non-thread-safe.
.IP "\(bu" 4
Never use non *\f(CW\*(C`_r\*(C'\fR functions unless it is explicitly documented that
-the function is tread\-safe.
+the function is tread-safe.
.IP "\(bu" 4
Every thread \s-1SHOULD\s0 call \f(CW\*(C`rrd_get_context()\*(C'\fR before its first call to
any \f(CW\*(C`librrd_th\*(C'\fR function in order to set up thread specific data. This
.IP "\(bu" 4
Always call \f(CW\*(C`rrd_error_clear()\*(C'\fR before any call to the
library. Otherwise the call might fail due to some earlier error.
-.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1RRD\s0 \s-1CONTRIBUTORS\s0"
+.SS "\s-1NOTES\s0 \s-1FOR\s0 \s-1RRD\s0 \s-1CONTRIBUTORS\s0"
.IX Subsection "NOTES FOR RRD CONTRIBUTORS"
Some precautions must be followed when developing \s-1RRD\s0 from now on:
.IP "\(bu" 4
Only use thread-safe functions in library code. Many often used libc
-functions aren't thread\-safe. Take care in the following
+functions aren't thread-safe. Take care in the following
situations or when using the following library functions:
.RS 4
.IP "\(bu" 4
@@ -179,7 +178,7 @@ Direct calls to \f(CW\*(C`strerror()\*(C'\fR must be avoided: use \f(CW\*(C`rrd_
instead, it provides a per-thread error message.
.IP "\(bu" 4
The \f(CW\*(C`getpw*\*(C'\fR, \f(CW\*(C`getgr*\*(C'\fR, \f(CW\*(C`gethost*\*(C'\fR function families (and some more
-\&\f(CW\*(C`get*\*(C'\fR functions) are not thread\-safe: use the *\f(CW\*(C`_r\*(C'\fR variants
+\&\f(CW\*(C`get*\*(C'\fR functions) are not thread-safe: use the *\f(CW\*(C`_r\*(C'\fR variants
.IP "\(bu" 4
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
*\f(CW\*(C`_r\*(C'\fR variants
that works with the \s-1GNU\s0 C\-preprocessor to \*(L"poison\*(R" some of the most
common non-thread-safe functions using the \f(CW\*(C`#pragma GCC poison\*(C'\fR
directive. Just include this header in source files you want to keep
-thread\-safe.
+thread-safe.
.IP "\(bu" 4
Do not introduce global variables!
.Sp
Do not use the \f(CW\*(C`rrd_parsetime\*(C'\fR function!
.Sp
It uses lots of global variables. You may use it in functions not designed
-to be thread\-safe, like in functions wrapping the \f(CW\*(C`_r\*(C'\fR version of some
+to be thread-safe, like in functions wrapping the \f(CW\*(C`_r\*(C'\fR version of some
operation (e.g., \f(CW\*(C`rrd_create\*(C'\fR, but not in \f(CW\*(C`rrd_create_r\*(C'\fR)
-.Sh "\s-1CURRENTLY\s0 \s-1IMPLEMENTED\s0 \s-1THREAD\s0 \s-1SAFE\s0 \s-1FUNCTIONS\s0"
+.SS "\s-1CURRENTLY\s0 \s-1IMPLEMENTED\s0 \s-1THREAD\s0 \s-1SAFE\s0 \s-1FUNCTIONS\s0"
.IX Subsection "CURRENTLY IMPLEMENTED THREAD SAFE FUNCTIONS"
Currently there exist thread-safe variants of \f(CW\*(C`rrd_update\*(C'\fR,
\&\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.