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, or if we can't use it because the execution order is wrong, then
  22 you'll get memory leaks.  Deal with it.
  23
  24 Several debugging variables that are not part of our official API are
  25 not protected by mutexes.  In general, the only way to set them is by
  26 changing the sources and recompiling, which obviously has no run-time
  27 thread safety issues, or by stopping the process under a debugger,
  28 which we blithely assert is "safe enough".
  29
  30 Debug code that we don't normally enable may be less thread safe than
  31 might be desired.  For example, multiple printf calls may be made,
  32 with the assumption that the output will not be intermixed with output
  33 from some other thread.  Offhand, I'm not aware of any cases where
  34 debugging code is "really" unsafe, as in likely to crash the program
  35 or produce insecure results.
  36
  37 Various libraries may call assert() and abort().  This should only be
  38 for "can't happen" cases, and indicate programming errors.  In some
  39 cases, the compiler may be able to infer that the "can't happen" cases
  40 really can't happen, and drop the calls, but in many cases, this is
  41 not possible.
  42
  43 There are cases (e.g., in the com_err library) where errors arising
  44 when dealing with other errors are handled by calling abort, for lack
  45 of anything better.  We should probably clean those up someday.
  46
  47 Various libraries call getenv().  This is perfectly safe, as long as
  48 nothing is calling setenv or putenv or what have you, while multiple
  49 threads are executing.  Of course, that severely curtails the ability
  50 to control our libraries through that "interface".
  51
  52 Various libraries call the ctype functions/macros (isupper, etc).  It
  53 is assumed that the program does not call setlocale, or does so only
  54 while the program is still single-threaded or while calls into the
  55 Kerberos libraries are not in progress.
  56
  57 The Windows thread safety support is unfinished.
  58
  59 I'm assuming that structure fields that are never written to (e.g.,
  60 after a structure has been initialized and *then* made possibly
  61 visible to multiple threads) are safe to read from one thread while
  62 another field is being updated by another thread.  If that's not the
  63 case, some more work is needed (and I'd like details on why it's not
  64 safe).
  65
  66 ----------------
  67
  68 libcom_err
  69
  70 Issues:
  71
  72 The callback hook support (set_com_err_hook, reset_com_err_hook, and
  73 calls to com_err and com_err_va) uses a mutex to protect the handle on
  74 the hook function.  As a side effect of this, if a callback function
  75 is registered which pops up a window and waits for the users'
  76 acknowledgement, then other errors cannot be reported by other threads
  77 until after the acknowledgement.  This could be fixed with
  78 multiple-reader-one-writer type locks, but that's a bit more
  79 complicated.
  80
  81 The string returned by error_message may be per-thread storage.  It
  82 can be passed off between threads, but it shouldn't be in use by any
  83 thread by the time the originating thread calls error_message again.
  84
  85 Error tables must no longer be in use (including pointers returned by
  86 error_message) when the library containing them is unloaded.
  87
  88 Temporary: A flag variable has been created in error_message.c which
  89 is used to try to catch cases where remove_error_table is called after
  90 the library finalization function.  This generally indicates
  91 out-of-order execution of the library finalization functions.  The
  92 handling of this flag is not thread-safe, but if the finalization
  93 function is called, other threads should in theory be finished with
  94 this library anyways.
  95
  96 Statics: error_message.c, com_err.c, covered above.
  97
  98 ----------------
  99
 100 libprofile (and its use in libkrb5)
 101
 102 Does no checks to see if it's opened multiple instances of the same
 103 file under different names.  Does not guard against trying to open a
 104 file while another thread or process is in the process of replacing
 105 it, or two threads trying to update a file at the same time.  The
 106 former should be pretty safe on UNIX with atomic rename, but on
 107 Windows there's a race condition; there's a window (so to speak) where
 108 the filename does not correspond to an actual file.
 109
 110 Statics: prof_file.c, a list of opened config files and their parse
 111 trees, and a mutex to protect it.
 112
 113 ----------------
 114
 115 libk5crypto
 116
 117 Uses of the Yarrow code from the krb5 crypto interface are protected
 118 by a single mutex.  Initialization of the Yarrow state will be done
 119 once, the first time these routines are called.  Calls directly to the
 120 Yarrow functions are not protected.
 121
 122 Uses ctype macros; what happens if the locale is changed in a
 123 multi-threaded program?
 124
 125 Debug var in pbkdf2.c.
 126
 127 Statics: pbkdf2.c: debug variable.
 128
 129 Statics: prng.c: Global Yarrow data and mutex.
 130
 131 Statics: crypto_libinit.c: library initializer aux data.
 132
 133 ----------------
 134
 135 libkrb5
 136
 137 (TBD)
 138
 139 Uses: ctype macros
 140
 141 Uses: getaddrinfo, getnameinfo.  According to current specifications,
 142 getaddrinfo should be thread-safe; some implementations are not, and
 143 we're not attempting to figure out which ones.  NetBSD 1.6, for
 144 example, had an unsafe implementation.
 145
 146 Uses: res_ninit, res_nsearch.  If these aren't available, the non-'n'
 147 versions will be used, and they are sometimes not thread-safe.
 148
 149 Uses: mkstemp, mktemp -- Are these, or our uses of them, likely to be
 150 thread-safe?
 151
 152 Uses: sigaction
 153
 154 The use of sigaction is in the code prompting for a password; we try
 155 to catch the keyboard interrupt character being used and turn it into
 156 an error return from that function.  THIS IS NOT THREAD-SAFE.
 157
 158 Uses: tcgetattr, tcsetattr.  This is also in the password-prompting
 159 code.  These are fine as long as no other threads are accessing the
 160 same terminal at the same time.
 161
 162 Uses: fopen.  This is thread-safe, actually, but a multi-threaded
 163 server is likely to be using lots of file descriptors.  On 32-bit
 164 Solaris platforms, fopen will not work if the next available file
 165 descriptor number is 256 or higher.  This can cause the keytab code to
 166 fail.
 167
 168 Statics: prompter.c: interrupt flag
 169
 170 Statics: ccdefops.c: default operations table pointer
 171
 172 Statics: ktdefname.c: variable to override default keytab name, NO
 173 LOCKING.  DON'T TOUCH THESE VARIABLES, at least in threaded programs.
 174
 175 Statics: conv_creds.c: debug variable
 176
 177 Statics: sendto_kdc.c: debug variable, in export list for KDC
 178
 179 Statics: parse.c: default realm cache, changed to not cache
 180
 181 Statics: krb5_libinit.c: lib init aux data
 182
 183 Statics: osconfig.c: various internal variables, probably should be const
 184
 185 Statics: init_ctx.c: "brand" string; not written.
 186
 187 Statics: cc_memory.c: list of caches, with mutex.
 188
 189 Statics: c_ustime.c: last timestamp, to implement "microseconds must
 190 always increment"
 191
 192 Statics: ktbase.c, ccbase.c, rc_base.c: type registries and mutexes.
 193
 194 ----------------
 195
 196 libgssapi_krb5
 197
 198 (TBD)
 199
 200 Uses: ctype macros
 201
 202 Statics: acquire_cred.c: name of keytab to use, and mutex.
 203
 204 Statics: gssapi_krb5.c:
 205
 206 Statics: init_sec_context.c:
 207
 208 Statics: set_ccache.c:
 209
 210 Statics: gssapi_generic.c: OID definitions, non-const by
 211 specification.  We probably could make them const anyways.
 212
 213 The keytab name saved away by krb5_gss_register_acceptor_identity is
 214 global and protected by a mutex; the ccache name stored by
 215 gss_krb5_ccache_name is per-thread.  This inconsistency is due to the
 216 anticipated usage patterns.
 217
 218 The old ccache name returned by gss_krb5_ccache_name if the last
 219 parameter is not a null pointer is also stored per-thread, and will be
 220 discarded at the next call to that routine from the same thread, or at
 221 thread termination.
 222
 223 Needs work: check various objects for thread safety
 224
 225 ----------------
 226
 227 libkrb4
 228 libdes425
 229
 230 I don't think we're likely to bother with these.
 231
 232 Part of the krb4 API requires keeping some internal storage across
 233 calls.
 234
 235 ----------------
 236
 237 libgssrpc
 238
 239 New version is in place.  Ignore it for now?
 240
 241 ----------------
 242
 243 libkadm5*
 244 libkdb5
 245
 246 Skip these for now.  We may want the KDC libraries to be thread-safe
 247 eventually, so the KDC can take better advantage of hyperthreaded or
 248 multiprocessor systems.
 249
 250 ----------------
 251
 252 libapputils
 253 libpty
 254 libss
 255
 256 Used by single-threaded programs only (but see above re KDC).  Don't
 257 bother for now.