Threading Model, configuration
This section describes how the Carmenta Engine configuration lock works and when and how to use it in an application.
Configuration
The configuration is the set of objects that generate map images or features. It consists of the objects; views, layers, operators, visualizers and datasets and all their properties; that are defined in a Carmenta Engine map configuration file but they can also be created through code in an application.
These objects are typically used in two ways:
Connecting a View to a MapControl to display maps in an application.
Calling GetFeatures on a layer or operator to programmatically get the features at a specific point in the layer/operator chain
As the figure below illustrates Carmenta Engine can use background threads when a view is being updated or GetFeatures has been called and part of the work can be performed on background threads that have been started by Carmenta Engine. This means that the objects that are accessed by Carmenta Engine to process features and render map images cannot be read or modified unless you synchronize all access correctly with the background threads.
 |
The configuration lock is used to synchronize access to the configuration so that Carmenta Engine's background threads do not access the data while it is being accessed.
Some members can be accessed safely without acquiring the configuration lock. See the Thread Safety section in the documentation for an individual property or method for more information.
Accessing the configuration efficiently
The configuration lock is what is called a reader/writer lock that allows either a single writer or multiple simultaneous readers access to the data protected by the lock. Carmenta Engine takes a reader lock internally, which can be done quickly, when it accesses the shared data of the configuration. An application can today only take the writer lock, with the help of the Guard class, when it wants to access the configuration. This is a relatively slow operation due to the fact that all active readers must finish before the writer lock can be acquired so an application should not take the configuration lock unnecessarily.
Even though an application is limited to taking the writer lock to the configuration, which can impact performance negatively, you can do the following to avoid acquiring it unnecessarily:
Make sure that all access, whether read or write, to the configuration that is not thread safe is executed on the main thread of the application, sometimes also called the GUI thread.
Take the configuration lock only when the configuration is modified.
If this is done correctly then the application can skip taking the configuration lock when it performs read operations on the GUI thread. The reason this works is due to the fact that all write operations are synchronized correctly with Carmenta Engine's background threads (since they both acquire the configuration lock) and the read operations will see the correct data since they are executed on the same thread that the application performs all write operations on.
The Thread Access Verifier will enforce these rules.