"Fossies" - the Fresh Open Source Software Archive

Member "krb5-1.18/doc/threads.txt" (12 Feb 2020, 4007 Bytes) of package /linux/misc/krb5-1.18.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "threads.txt" see the Fossies "Dox" file reference documentation.

    1 Thread safety in the MIT Kerberos libraries
    2 
    3 The return value from krb5_cc_default_name is a handle on internal
    4 storage from the krb5_context.  It is valid only until
    5 krb5_cc_set_default_name or krb5_free_context is called.  If
    6 krb5_cc_set_default_name may be called, the calling code must ensure
    7 that the storage returned by krb5_cc_default_name is no longer in use
    8 by that time.
    9 
   10 Any use of krb5_context must be confined to one thread at a time by
   11 the application code.
   12 
   13 Uses of credentials caches, replay caches, and keytabs may happen in
   14 multiple threads simultaneously as long as none of them destroys the
   15 object while other threads may still be using it.  (Any internal data
   16 modification in those objects will be protected by mutexes or other
   17 means, within the krb5 library.)
   18 
   19 The simple, exposed data structures in krb5.h like krb5_principal are
   20 not protected; they should not be used in one thread while another
   21 thread might be modifying them.  (TO DO: Build a list of which calls
   22 keep references to supplied data or return references to
   23 otherwise-referenced data, as opposed to everything making copies.)
   24 
   25 
   26 
   27 [ This part is a little outdated already. ]
   28 
   29    // Between these two, we should be able to do pure compile-time
   30    // and pure run-time initialization.
   31    //   POSIX: partial initializer is PTHREAD_MUTEX_INITIALIZER,
   32    //          finish does nothing
   33    //   Windows: partial initializer is zero/empty,
   34    //            finish does the actual work and runs at load time
   35    //   debug: partial initializer sets one magic value,
   36    //          finish verifies, sets a new magic value
   37    k5_mutex_t foo_mutex = K5_MUTEX_PARTIAL_INITIALIZER;
   38    int k5_mutex_finish_init(k5_mutex_t *);
   39    // for dynamic allocation
   40    int k5_mutex_init(k5_mutex_t *);
   41    // Must work for both kinds of allocation, even if it means adding
   42    // a flag.
   43    int k5_mutex_destroy(k5_mutex_t *);
   44    //
   45    // Per library, one function to finish the static mutex
   46    // initialization.
   47    //
   48    // A second function called at various possible "first" entry
   49    // points which either calls pthread_once on the first function
   50    // (POSIX), or checks some flag set by the first function (Windows,
   51    // debug support), and possibly returns an error.
   52    //
   53    // A third function for library termination calls mutex_destroy on
   54    // each mutex for the library.
   55    //
   56    // 
   57    int k5_mutex_lock(k5_mutex_t *);
   58    int k5_mutex_unlock(k5_mutex_t *);
   59    // Optional (always defined, but need not do anything):
   60    void k5_mutex_assert_locked(k5_mutex_t *);
   61    void k5_mutex_assert_unlocked(k5_mutex_t *);
   62 
   63 
   64    k5_key_t key;
   65    int k5_key_create(k5_key_t *, void (*destructor)(void *));
   66    void *k5_getspecific(k5_key_t);
   67    int k5_setspecific(k5_key_t, const void *);
   68    ... stuff to signal library termination ...
   69 
   70 This is **NOT** an exported interface, and is subject to change.
   71 
   72 On many platforms with weak reference support, we can declare certain
   73 symbols to be weak, and test the addresses before calling them.  The
   74 references generally will be non-null if the application pulls in the
   75 pthread support.  Sometimes stubs are present in the C library for
   76 some of these routines, and sometimes they're not functional; if so,
   77 we need to figure out which ones, and check for the presence of some
   78 *other* routines.
   79 
   80 AIX 4.3.3 doesn't support weak references.  However, it looks like
   81 calling dlsym(NULL) causes the pthread library to get loaded, so we're
   82 going to just go ahead and link against it anyways.
   83 
   84 On Tru64 we also link against the thread library always.
   85 
   86 
   87 For now, the basic model is:
   88 
   89   If weak references are supported, use them.
   90   Else, assume support is present; if that means explicitly pulling in
   91   the thread library, so be it.
   92 
   93 
   94 
   95 The locking described above may not be sufficient, at least for good
   96 performance.  At some point we may want to switch to read/write locks,
   97 so multiple threads can grovel over a data structure at once as long
   98 as they don't change it.
   99 
  100 
  101 See also notes in src/include/k5-thread.h.