user/rrdtool/doc/rrdthreads.txt

   1 RRDTHREADS(1)                rrdtool                RRDTHREADS(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        rrdthreads - Provisions for linking the RRD library to use
   7        in multi-threaded programs
   8
   9 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
  10        Using librrd in multi-threaded programs requires some
  11        extra precautions, as the RRD library in its original form
  12        was not thread-safe at all. This document describes
  13        requirements and pitfalls on the way to use the multi-
  14        threaded version of librrd in your own programs. It also
  15        gives hints for future RRD development to keep the library
  16        thread-safe.
  17
  18        Currently only some RRD operations are implemented in a
  19        thread-safe way. They all end in the usual ""_r"" suffix.
  20
  21 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  22        In order to use librrd in multi-threaded programs you
  23        must:
  24
  25        +\bo   Link with _\bl_\bi_\bb_\br_\br_\bd_\b__\bt_\bh instead of _\bl_\bi_\bb_\br_\br_\bd (use "-lrrd_th"
  26            when linking)
  27
  28        +\bo   Use the ""_r"" functions instead of the normal API-
  29            functions
  30
  31        +\bo   Do not use any at-style time specifications. Parsing
  32            of such time specifications is terribly
  33            non-thread-safe.
  34
  35        +\bo   Never use non *"_r" functions unless it is explicitly
  36            documented that the function is tread-safe.
  37
  38        +\bo   Every thread SHOULD call "rrd_get_context()" before
  39            its first call to any "librrd_th" function in order to
  40            set up thread specific data. This is not strictly
  41            required, but it is the only way to test if memory
  42            allocation can be done by this function. Otherwise the
  43            program may die with a SIGSEGV in a low-memory situa-
  44            tion.
  45
  46        +\bo   Always call "rrd_error_clear()" before any call to the
  47            library. Otherwise the call might fail due to some
  48            earlier error.
  49
  50        N\bNO\bOT\bTE\bES\bS F\bFO\bOR\bR R\bRR\bRD\bD C\bCO\bON\bNT\bTR\bRI\bIB\bBU\bUT\bTO\bOR\bRS\bS
  51
  52        Some precautions must be followed when developing RRD from
  53        now on:
  54
  55        +\bo   Only use thread-safe functions in library code. Many
  56            often used libc functions aren't thread-safe. Take
  57            care in the following situations or when using the
  58            following library functions:
  59
  60            +\bo   Direct calls to "strerror()" must be avoided: use
  61                "rrd_strerror()" instead, it provides a per-thread
  62                error message.
  63
  64            +\bo   The "getpw*", "getgr*", "gethost*" function fami-
  65                lies (and some more "get*" functions) are not
  66                thread-safe: use the *"_r" variants
  67
  68            +\bo   Time functions: "asctime", "ctime", "gmtime",
  69                "localtime": use *"_r" variants
  70
  71            +\bo   "strtok": use "strtok_r"
  72
  73            +\bo   "tmpnam": use "tmpnam_r"
  74
  75            +\bo   Many others (lookup documentation)
  76
  77        +\bo   A header file named _\br_\br_\bd_\b__\bi_\bs_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\ba_\bf_\be_\b._\bh is provided
  78            that works with the GNU C-preprocessor to "poison"
  79            some of the most common non-thread-safe functions
  80            using the "#pragma GCC poison" directive. Just include
  81            this header in source files you want to keep
  82            thread-safe.
  83
  84        +\bo   Do not introduce global variables!
  85
  86            If you really, really have to use a global variable
  87            you may add a new field to the "rrd_context" structure
  88            and modify _\br_\br_\bd_\b__\be_\br_\br_\bo_\br_\b._\bc, _\br_\br_\bd_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\ba_\bf_\be_\b._\bc and
  89            _\br_\br_\bd_\b__\bn_\bo_\bn_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\ba_\bf_\be_\b._\bc
  90
  91        +\bo   Do not use "getopt" or "getopt_long" in *"_r" (neither
  92            directly nor indirectly).
  93
  94            "getopt" uses global variables and behaves badly in a
  95            multi-threaded application when called concurrently.
  96            Instead provide a *_r function taking all options as
  97            function parameters. You may provide argc and **argv
  98            arguments for variable length argument lists. See
  99            "rrd_update_r" as an example.
 100
 101        +\bo   Do not use the "parsetime" function!
 102
 103            It uses lots of global variables. You may use it in
 104            functions not designed to be thread-safe, like in
 105            functions wrapping the "_r" version of some operation
 106            (e.g., "rrd_create", but not in "rrd_create_r")
 107
 108        C\bCU\bUR\bRR\bRE\bEN\bNT\bTL\bLY\bY I\bIM\bMP\bPL\bLE\bEM\bME\bEN\bNT\bTE\bED\bD T\bTH\bHR\bRE\bEA\bAD\bD S\bSA\bAF\bFE\bE F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bNS\bS
 109
 110        Currently there exist thread-safe variants of
 111        "rrd_update", "rrd_create", "rrd_dump", "rrd_info" and
 112        "rrd_last".
 113
 114 A\bAU\bUT\bTH\bHO\bOR\bR
 115        Peter Stamfest <peter@stamfest.at>
 116
 117
 118
 119 1.2.10                      2005-06-17              RRDTHREADS(1)