Threading Overview

The cxsource framework is built with the assumption of preemptive multithreading. While many classes can be used in a single-threaded environment, there is often no provision for (non-threaded) asynchronous IO, non-blocking operations, etc. which makes this technique illsuited for many production uses.

 

Thread Safety Models

Thread safety is provided in one of a few manners, depending on the intended usage of each class. While each class should explain its thread safety in detail, the following overview helps understand the choices made.

• Objects which are not thread-safe. This means that they must be used ONLY on the thread which created them. In most cases, this comes with the additional restriction that they must be used ONLY on the program's main thread.
  • This typically affects Native User Interface components, where the underlying OS is likely to have thread safety limitations.
  • Since cxsource is cross-platform, we make the assumption that all Native User Interfaces are usable only on the main thread.
  • This isn't a significant limitation in practice, because attempting to manipulate a UI on multiple threads (while the user is also potentially doing something on other threads) is difficult-to-synchronise at best, and because the user interface code should always be high-performance to give the best user experience (meaning that it should not be running on the same thread as any heavy or blocking application logic).
• Objects which are not re-entrant, but are thread safe. Most classes fall into this category. It is permissable to manipulate the object on any thread, but not on multiple threads simultaneously. If you intend to manipulate the object on multiple threads, you must perform your own locking to avoid re-entrance.
  • Classes which do not define any particular thread-safety guidelines should be assumed to fall under this category.
• Objects where a small number of methods are explicitly thread safe.
  • Objects which implement blocking behaviours are often not re-entrant in the general sense, but may offer some form of "cancellation" or "wakeup" mechanism that can be called from another thread.
  • Objects may be built to operate only on a single thread, but accept some form(s) of messages from other threads.
• Objects for which the entire public interface is thread-safe. This applies to locking primitives and some forms of shared data cache.
  • Care should be taken to distinguish the thread-safe object itself, and any data that might be provided. For example, even if a particular object cache is guaranteed entirely thread-safe, the objects retrieved from that cache may have their own thread-safety limitations.