Click or drag to resize

Multithreading

STK Components is designed for multithreading. Many of the operations it performs, such as propagating and computing Access, are automatically performed in parallel using multiple threads. This enables the library to take full advantage of modern multi-core processors.

Note Note

Insight3D has a different threading policy than the rest of STK Components. See the Insight3D section below.

Threading in STK Components

You can control STK Components' use of threads by changing the ThreadingPolicy. The threading policy is configuration information, associated with each thread, that controls how parallelizable operations started by that thread make use of threads. By default, the policy specifies that parallelizable operations create one thread per logical processor on the system. For example, if your system has four cores, and each core is HyperThreaded (meaning that it supports two hardware threads), STK Components will automatically create and utilize eight threads to compute Access, Coverage, etc.

You can specify the number of threads to use by setting the NumberOfThreads (get / set) property. For example, the following code specifies that parallelizable operations created by the current thread should use exactly five threads to perform their work.

Java
ThreadingPolicy.setNumberOfThreads(5);

You can also disable multithreading entirely by setting NumberOfThreads (get / set) to one, or by calling the configureToUseCurrentThreadOnly method. When the threading policy is configured to use only one thread, parallelizable operations are executed using the calling thread and no additional threads are created.

Java
ThreadingPolicy.configureToUseCurrentThreadOnly();

New threads are either recruited from the thread pool or are created explicitly for use by the parallelizable operation, depending on the value of the ThreadSource (get / set) property. By default, threads are recruited from the thread pool. The following code changes the property so that new threads are created instead:

Java
ThreadingPolicy.setThreadSource(ThreadSource.NEW_THREAD);

Recruiting threads from the thread pool is usually much faster than creating them directly. However, it is sometimes useful to avoid using the thread pool so that the pool is not monopolized by a long-running operation.

Thread Safety

This kind of library-wide multithreading requires careful attention to thread safety throughout the library. It is important to be aware when a type is safe for use by multiple threads simultaneously and when it is not.

In general, all types in STK Components (with the major exception of Insight3D - see below) are thread-safe for read-only access. In other words, it is safe to call methods and access properties on instances simultaneously from multiple threads as long as the methods and properties do not modify the state of the object. However, if one thread modifies the object while another thread is reading properties or executing methods, the second thread may experience an inconsistent state of the object or the object may throw exceptions.

In addition, static methods and properties are safe to use from multiple threads simultaneously. Also, it is safe to use two different instances of the same type from multiple threads simultaneously. And a single instance can be freely used from any thread (or even multiple threads) as long as you ensure that only one thread at a time is accessing it. Exceptions to any of these rules, in the rare cases where they occur, will be clearly stated in the reference documentation.

Some types in STK Components, most notably Evaluators, implement the IThreadAware interface. Types that implement this interface might not even be thread-safe for read-only access as described above. If the IsThreadSafe (get) property on this interface returns true, the instance can be assumed to be just as thread-safe as most objects in STK Components; you can use the instance from multiple threads simultaneously as long as no thread is modifying the instance. If it returns false, however, the instance must not be used from multiple threads simultaneously under any circumstances.

Fortunately, all types that implement IThreadAware also implement ICloneWithContext, which means that you can use CopyForAnotherThread to make a copy of the instance. Then, the original and any copies can be used from multiple threads simultaneously. Furthermore, it is safe to copy the instance for another thread from multiple threads simultaneously, as long as no thread is modifying the instance at the same time.

The following code creates a PointEvaluator (which implements IThreadAware) to evaluate the location of a Point and then prepares to pass it to a new thread:

Java
PointEvaluator evaluator = point.getEvaluator();
PointEvaluator evaluatorForNewThread = CopyForAnotherThread.copy(evaluator);

CopyForAnotherThread can safely be used on any type that implements IThreadAware, whether or not it reports itself as thread-safe. When CopyForAnotherThread.copy is invoked on a type that is thread-safe, it returns the existing instance without making another copy of it.

Insight3D

Insight3D currently does not support multithreading. All interaction with Insight3D types must be done from a single thread. It is NOT guaranteed to be safe to use Insight3D types from multiple threads even if the user ensures that only one thread at a time is interacting with Insight3D.