6.2 Threads in Crystal Space

Written by Jorrit Tyberghein.

The Crystal Space project as such is not thread-safe. So when using threads in combination with Crystal Space you have to be careful. However, several parts of Crystal Space are thread-safe to some degree. This is documented in this section. However, by default you must assume that some Crystal Space plugin or module is not thread-safe unless it is mentioned here.

Threadsafe parts of Crystal Space

• SCF (see section Shared Class Facility (SCF)) class loading/unloading is safe. This means that SCF_CREATE_INSTANCE() and all the routines in `iSCF' that have to do with loaded classes are safe.
• The plugin manager is safe, thus functions such as csLoadPlugin, csLoadPluginAlways, and csQueryPluginClass are safe.
• The object registry is safe, thus macros like csQueryRegistry are safe. The iObjectRegistryIterator takes a copy of the data over which it iterates so it will not even lock.
• VFS (see section Virtual File System (VFS)) is thread-safe for most operations. But do not work on the same `iFile' from different threads! That is not thread-safe. Also the concept of the current directory is not really valid with threads.
• The TinyXML, XMLRead, and BinaryXML parsers are thread safe in the sense that it is okay to create and work on separate documents in separate threads. However it is not okay to work on the same document in different threads.
• The syntax services plugin is safe for the basic parsing tools (vectors, matrices, reporting errors, etc.). For polygons and thing related objects this has not yet been checked for safety.
• The `simpcon' and `csconout' output consoles are thread-safe provided auto-updating is disabled which you can set like this:

  csRef<iConsoleOutput> con = ...; con->AutoUpdate(false);

  Note that by default auto-updating is enabled!

• The reporter plugin is fully thread-safe.
• The standard reporter listener plugin is thread-safe for basic operations but not for initialization. That should be done from the main thread. Also note that thread-safety of the standard reporter listener depends on thread-safety of the output console that is being used.
• The following mesh object and factory loaders are thread-safe provided that the implementation of `iLoaderContext' is thread-safe. Please note that the default iLoaderContext is not thread-safe which makes all loader plugins unsafe by default.
  • Genmesh loader: Aside from a small design mistake with streams in case the new renderer is used, the genmesh loader plugin is perfectly thread-safe.

Threaded Loading

One important threaded section of Crystal Space is the threaded loader. In order to ensure that the threaded loader works correctly you must make sure that you use thread-safe versions of the following modules in Crystal Space:

• iReporter (the standard reporter is okay).
• iReporterListener (the standard reporter listener is okay).
• iConsoleOutput (`simpcon' and `csconout' are okay provided auto-updating is disabled).
• iLoaderContext (the threaded loader provides a thread-safe version of this one).
• iDocumentSystem (TinyXML, XMLRead, and BinaryXML are all okay).

This document was generated using texi2html 1.76.