doc/thread-safe.txt

   1 In general, it's assumed that the library initialization function (if
   2 initialization isn't delayed) and the library finalization function
   3 are run in some thread-safe fashion, with no other parts of the
   4 library in question in use.  (If dlopen or dlsym in one thread starts
   5 running the initializer, and then dlopen/dlsym in another thread
   6 returns and lets you start accessing functions or data in the library
   7 before the initializer is finished, that really seems like a
   8 dlopen/dlsym bug.)
   9
  10 It's also assumed that if library A depends on library B, then library
  11 B's initializer runs first, and its finalizer last, whether loading
  12 dynamically at run time or at process startup/exit.  (It appears that
  13 AIX 4.3.3 may violate this, at least when we use gcc's
  14 constructor/destructor attributes in shared libraries.)
  15
  16 Support for freeing the heap storage allocated by a library has NOT,
  17 in general, been written.  There are hooks, but often they ignore some
  18 of the library's local storage, mutexes, etc.
  19
  20 If shared library finalization code doesn't get run at all at dlclose
  21 time, then you'll get memory leaks.  Deal with it.
  22
  23 Several debugging variables that are not part of our official API are
  24 not protected by mutexes.  In general, the only way to set them is by
  25 changing the sources and recompiling, which obviously has no run-time
  26 thread safety issues, or by stopping the process under a debugger,
  27 which we blithely assert is "safe enough".
  28
  29 Various libraries may call assert() and abort().  This should only be
  30 for "can't happen" cases, and indicate programming errors.  In some
  31 cases, the compiler may be able to infer that the "can't happen" cases
  32 really can't happen, and drop the calls, but in many cases, this is
  33 not possible.
  34
  35 There are cases (e.g., in the com_err library) where errors arising
  36 when dealing with other errors are handled by calling abort, for lack
  37 of anything better.  We should probably clean those up someday.
  38
  39 Various libraries call getenv().  This is perfectly safe, as long as
  40 nothing is calling setenv or putenv or what have you.  Of course, that
  41 severely curtails the ability to control our libraries through that
  42 "interface".
  43
  44 ----------------
  45
  46 libcom_err
  47
  48 Issues:
  49
  50 The callback hook support (set_com_err_hook, reset_com_err_hook, and
  51 calls to com_err and com_err_va) uses a mutex to protect the handle on
  52 the hook function.  As a side effect of this, if a callback function
  53 is registered which pops up a window and waits for the users'
  54 acknowledgement, then other errors cannot be reported by other threads
  55 until after the acknowledgement.  This could be fixed with
  56 multiple-reader-one-writer type locks, but that's a bit more
  57 complicated.
  58
  59 The Windows thread safety support is unfinished.
  60
  61 The string returned by error_message may be per-thread storage.  It
  62 can be passed off between threads, but it shouldn't be in use by any
  63 thread by the time the originating thread calls error_message again.
  64
  65 Error tables must no longer be in use (including pointers returned by
  66 error_message) when the library containing them is unloaded.
  67
  68 ----------------
  69
  70 libprofile (and its use in libkrb5)
  71
  72 Does no checks to see if it's opened multiple instances of the same
  73 file under different names.  Does not guard against trying to open a
  74 file while another thread or process is in the process of replacing
  75 it, or two threads trying to update a file at the same time.  The
  76 former should be pretty safe on UNIX with atomic rename, but on
  77 Windows there's a race condition; there's a window (so to speak) where
  78 the filename does not correspond to an actual file.
  79
  80 ----------------
  81
  82 libk5crypto
  83
  84 Uses of the Yarrow code from the krb5 crypto interface are protected
  85 by a single mutex.  Initialization of the Yarrow state will be done
  86 once, the first time these routines are called.  Calls directly to the
  87 Yarrow functions are not protected.
  88
  89 Uses ctype macros; what happens if the locale is changed in a
  90 multi-threaded program?
  91
  92 Debug var in pbkdf2.c.
  93
  94 ----------------
  95
  96 libkrb5
  97
  98 (TBD)
  99
 100 Uses: ctype macros
 101
 102 Uses: res_search, dn_expand, getaddrinfo, getservbyname, getnameinfo
 103
 104 According to current specifications, getaddrinfo should be
 105 thread-safe; some implementations are not, and we're not attempting to
 106 figure out which ones.
 107
 108 Uses: getpwname, getpwuid -- should use _r versions if available
 109
 110 Uses: gmtime, localtime -- should use _r versions
 111
 112 Uses: mkstemp, mktemp -- Are these, or our uses of them, likely to be
 113 thread-safe?
 114
 115 Uses: regcomp, regexec
 116
 117 Uses: sigaction
 118
 119 The use of sigaction is in the code prompting for a password; we try
 120 to catch the keyboard interrupt character being used and turn it into
 121 an error return from that function.
 122
 123 ----------------
 124
 125 libgssapi_krb5
 126
 127 (TBD)
 128
 129 Uses: ctype macros
 130
 131 Uses: getpwuid
 132
 133 Some static data.
 134
 135 ----------------
 136
 137 libkrb4
 138 libdes425
 139
 140 I don't think we're likely to bother with these.
 141
 142 Part of the krb4 API requires keeping some internal storage across
 143 calls.
 144
 145 ----------------
 146
 147 libgssrpc
 148
 149 Skip this.  We're replacing it anyways.
 150
 151 ----------------
 152
 153 libkadm5*
 154 libkdb5
 155
 156 Skip these for now.  We may want the KDC libraries to be thread-safe
 157 eventually, so the KDC can take better advantage of hyperthreaded or
 158 multiprocessor systems.
 159
 160 ----------------
 161
 162 libapputils
 163 libpty
 164 libss
 165
 166 Used by single-threaded programs only (but see above re KDC).  Don't
 167 bother for now.