Galaxy Communicator Documentation:

Thread Notes

License / Documentation home / Help and feedback




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.

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: 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: 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.


License / Documentation home / Help and feedback
Last updated July 9, 2002