Galaxy Communicator Documentation:
Thread Notes
Overview
The core Galaxy Communicator library is believed to be thread-safe on
a number of platforms, which are listed in the table in the installation documentation. The
thread implementation in Communicator uses POSIX threads on Unix, and native
NT threads on NT.
On Unix, if you wish to have the option of compiling a threaded version
of a library or executable, insert the line
THREAD_SAFE = 1
into the MIT Makefile before rules.make is loaded. This will enable the
compilation targets thread,
thread-debug, thread-profile, thread-purify and
thread-insure. If THREAD_SAFE has not been set, these targets will
be equivalent to the non-threaded versions. MITRE has provided an (experimental)
option for toplevel server operation which uses threads instead of timed tasks
for server and connection management. As of version 3.0, this option works
on Windows as well as Unix.
If you use non-MIT makefiles, including project files on Win32,
make sure that -DGAL_THREADS -D_REENTRANT are among your compilation
flags.
Due to some backward compatibility issues, we have let remain a situation
in the output code where the variable which controls verbosity levels may
be initialized (harmlessly) more than once.
The Hub is not completely thread-safe, due to calls to rand() and localtime().
These will be fixed in a subsequent distribution.
What's protected and what's
not
Many of the basic elements in the core library are mutex-protected at various
points, but some are not. Here's a quick guide. The Communicator library
has a set of undocumented calls
which manage mutexes on multiple platforms, the usage of which is fairly
transparent. You can use these, or native calls to POSIX or Win32 threads.
- Frames and objects. The internal memory store is mutex-protected,
but the individual frames and objects are not. The core library does not
share objects internally, so this isn't a problem for the library, but if
you have individual frames or objects which may be modified by more than
one thread, you must set up a mutex.
- Connections and servers. Connections and servers are fully mutex-protected.
The core library supports multiple threads reading from or writing to the
same connection.
- Environments. Environments are not mutex-protected in any way.
- Brokers. Because brokers use standard connection objects for
communication, they inherit the mutex-protection benefits associated with
connections and servers. However, other access to brokers (for instance,
multiple threads attempting to update broker callbacks simultaneously) is
not protected, since it doesn't happen in the core library.
Threads and task/broker/proxy
creation
The functions which create timed tasks,
brokers and proxies all accept
an argument which specifies the polling interval for the task associated
with the entity. Until release 4.0, it was not possible to create these elements
without starting them, and this turned out to be a serious problem for thread
support, because it was at times necessary to set callbacks and other properties
of these objects before their polling began. In 4.0, it is now possible to
create these elements with a polling interval of -1, and start them later.
If you intend to use tasks as threads (the -thread command line
argument), and you need to set additional callbacks or properties of these
elements before the threads begin, you must be careful to start the polling
only after everything has been set up.
Signals
The Communicator library provides two
functions for signal handling, which are guaranteed to do the right things
in both threaded and non-threaded cases. Please use these functions to install
signal handlers (and to initialize signal handling, if you're writing your
own toplevel loop).
Status
The core library consistently passes our tests for thread safety on a range
of platforms, but these tests are incomplete. In version 4.0, we corrected
a number of lurking bugs having to do with not having protected a range of
potential thread cancellation points. This fix seems to have allowed the
core library to work in some very sophisticated threading situations. However,
we're still aware of an intermittent threading bug which seems to manifest
itself with outgoing brokers with multiple connections. We do not know what
the nature of this bug is yet.
Platform notes
Sparc Solaris
The Communicator library uses the following reentrant versions of functions:
- gethostbyname_r()
- strtok_r()
The library also uses a homemade version of inet_ntoa() due to some unfortunate
interactions with Tcl observed by the MIT folks. inet_ntoa_r() is available
in Solaris, but is not documented.
RedHat Linux
The Communicator library uses the following reentrant versions of functions:
- gethostbyname_r()
- strtok_r()
The library also uses a homemade version of inet_ntoa() due to some unfortunate
interactions with Tcl observed by the MIT folks. The library also provides
a thread-safe version of strerror(), which appears not to be thread-safe in
this version of Linux.
It appears that RedHat 5.2 might also support a thread-safe compilation
of the core library. RedHat 4.2 is pre-glibc and may not have the appropriate
thread support.
Windows NT
The Windows NT functions gethostbyname(), inet_ntoa() and strtok() are
thread-safe. The NT documentation does not make it clear whether strerror()
is thread-safe.
Other platforms
If you enable threads for the core Communicator compilation and your compilation
fails because any of these functions are missing, the chances are you will
not be able to enable threads. Even if you write a wrapper function with the
appropriate mutex protection, you will not be able to protect the calls in
the core Communicator library and the results will be unsafe behavior. If
you need support enabling threads on a platform not described here, please
contact us.
Last updated July 9, 2002