$DragonFly: src/lib/libpthread/README,v 1.1 2007/04/17 12:34:07 corecode Exp $

Proxy libpthread
================

We want to be able to switch between threading libraries at execution
time.  This problem is solved by this proxy libpthread.  Its operation is
as follows.

During link time a library is needed which defines all necessary pthread
functions.  By linking libpthread.so to any threading lib (default is
libc_r.so), this requirement is (indirectly) met.

Unfortuately ld wants to link in also recursively DT_NEEDED libs if any
specified object needs a symbol from these libs.  We cheat by doing the
following:  libc.so anyways defines all pthread functions as weak symbols
except for pthread_create.  libpthread.so now also defines a dummy
pthread_create as weak symbol and ld is satisfied.  At execution time
later rtld will resolve all these references to the strong symbols in the
right thread library.

Allowing the user to switch the threading lib works like this:  At link
time ld reads the SONAME of libpthread.so, which is set to libpthread.so.0
(or a higher major, if ABI changes).  Usually libfoo.so is a symlink to
libfoo.so.3 which also has set its SONAME to libfoo.so.3, so that if
libfoo.so.4 is being installed, programs will still continue to use
libfoo.so.3 and not follow the symlink libfoo.so to the newer -- and
possibly incompatible -- libfoo.so.4.  What we do is approximately the
opposite:  libpthread.so is no symlink, but nevertheless has its SONAME
set to libpthread.so.0.  Now, however, libpthread.so.0 is a symlink to the
threading library of your choice.  The linker will use the default
threading lib which libpthread.so is linked to, but the runtime linker
will instead follow the symlink.

This (obviously) does not work for static linking.