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

3 files changed, 35 insertions, 7 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 704360603..6e27bd034 100644
--- 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 9e3070681..0996b329a 100644
--- 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 1b655ea0c..b161dafbc 100644
--- 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.