update thread support doc

* threads.txt, thread-safety.txt: Updates.

ticket: new
target_version: 1.4
tags: pullup

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@16991 dc483132-0cff-0310-8789-dd5450dbe970

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 704360603faca38079f828454cd62f42855f2189..6e27bd034ecdc91f0142acdb6d8cd5067a2f23df 100644 (file)
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -8,6 +8,8 @@
        * implementor.texinfo (Host Address Lookup): Document Mac OS X
        issues.
 
+       * threads.txt, thread-safety.txt: Updates.
+
 2004-11-19  Tom Yu  <tlyu@mit.edu>
 
        * build.texinfo (Solaris 9): Document Solaris patches for pty

diff --git a/doc/thread-safe.txt b/doc/thread-safe.txt
index 9e307068103e5667da8daaf168b2a315712dc4ce..0996b329a0ee65b847d1d152773d57d45a71aea9 100644 (file)
--- a/doc/thread-safe.txt
+++ b/doc/thread-safe.txt
@@ -140,10 +140,11 @@ Uses: ctype macros
 
 Uses: getaddrinfo, getnameinfo.  According to current specifications,
 getaddrinfo should be thread-safe; some implementations are not, and
-we're not attempting to figure out which ones.
+we're not attempting to figure out which ones.  NetBSD 1.6, for
+example, had an unsafe implementation.
 
 Uses: res_ninit, res_nsearch.  If these aren't available, the non-'n'
-versions will be used, and they are not thread-safe.
+versions will be used, and they are sometimes not thread-safe.
 
 Uses: mkstemp, mktemp -- Are these, or our uses of them, likely to be
 thread-safe?
@@ -158,17 +159,24 @@ Uses: tcgetattr, tcsetattr.  This is also in the password-prompting
 code.  These are fine as long as no other threads are accessing the
 same terminal at the same time.
 
+Uses: fopen.  This is thread-safe, actually, but a multi-threaded
+server is likely to be using lots of file descriptors.  On 32-bit
+Solaris platforms, fopen will not work if the next available file
+descriptor number is 256 or higher.  This can cause the keytab code to
+fail.
+
 Statics: prompter.c: interrupt flag
 
 Statics: ccdefops.c: default operations table pointer
 
-Statics: ktdefname.c: variable to override default keytab name, NEEDS LOCKING
+Statics: ktdefname.c: variable to override default keytab name, NO
+LOCKING.  DON'T TOUCH THESE VARIABLES, at least in threaded programs.
 
 Statics: conv_creds.c: debug variable
 
 Statics: sendto_kdc.c: debug variable, in export list for KDC
 
-Statics: parse.c: default realm cache, NOT THREAD SAFE
+Statics: parse.c: default realm cache, changed to not cache
 
 Statics: krb5_libinit.c: lib init aux data
 
@@ -183,8 +191,6 @@ always increment"
 
 Statics: ktbase.c, ccbase.c, rc_base.c: type registries and mutexes.
 
-Needs work: keytab locking
-
 ----------------
 
 libgssapi_krb5

diff --git a/doc/threads.txt b/doc/threads.txt
index 1b655ea0ce8f1aeac6ae3c423bb80fbc85e6abf9..b161dafbc6d887554101e88111a6f22974b9f275 100644 (file)
--- a/doc/threads.txt
+++ b/doc/threads.txt
@@ -16,6 +16,16 @@ object while other threads may still be using it.  (Any internal data
 modification in those objects will be protected by mutexes or other
 means, within the krb5 library.)
 
+The simple, exposed data structures in krb5.h like krb5_principal are
+not protected; they should not be used in one thread while another
+thread might be modifying them.  (TO DO: Build a list of which calls
+keep references to supplied data or return references to
+otherwise-referenced data, as opposed to everything making copies.)
+
+
+
+[ This part is a little outdated already. ]
+
    // Between these two, we should be able to do pure compile-time
    // and pure run-time initialization.
    //   POSIX: partial initializer is PTHREAD_MUTEX_INITIALIZER,
@@ -57,6 +67,7 @@ means, within the krb5 library.)
    int k5_setspecific(k5_key_t, const void *);
    ... stuff to signal library termination ...
 
+This is **NOT** an exported interface, and is subject to change.
 
 On many platforms with weak reference support, we can declare certain
 symbols to be weak, and test the addresses before calling them.  The
@@ -70,12 +81,21 @@ AIX 4.3.3 doesn't support weak references.  However, it looks like
 calling dlsym(NULL) causes the pthread library to get loaded, so we're
 going to just go ahead and link against it anyways.
 
+On Tru64 we also link against the thread library always.
+
 
 For now, the basic model is:
 
   If weak references supported, use them.
-  Else, assume support is present.
+  Else, assume support is present; if that means explicitly pulling in
+  the thread library, so be it.
+
+
 
+The locking described above may not be sufficient, at least for good
+performance.  At some point we may want to switch to read/write locks,
+so multiple threads can grovel over a data structure at once as long
+as they don't change it.
 
 
 See also notes in src/include/k5-thread.h.