Thread Access Verifier
This section provides information about the built-in thread access verifier that enforces some threading rules when accessing Carmenta Engine objects.
The Python API does not enforce threading rules.
Using the Thread Access Verifier
The thread access verifier is active by default, the performance cost is negligible, and we recommend that all applications leave it enabled to help catch a set of threading errors common in Carmenta Engine applications that can be hard to find by other methods.
What does the Thread Access Verifier check?
The thread access verifier helps enforce the recommended best practices for accessing objects and properties that should only be accessed from the GUI thread and that require the application taking the configuration lock before the object is modified. To verify that an application follows the rules Carmenta Engine keeps track of when objects; layers, operators, visualizers, attribute variables as well as some other classes; are part of a View and adds runtime checks to enforce the following rules:
That objects and members that should only be accessed from the GUI thread and are part of a view (or is a View) are accessed from the GUI thread.
That non thread-safe configuration objects and members that belong to a view are read from the GUI thread.
That non thread-safe configuration objects and members that belong to a view are modified from the GUI thread while the application holds the configuration lock.
Carmenta Engine will throw an exception at the point in the code where an application breaks a rule making it easy to find and fix.
The Thread Access Verifier cannot check that the rules are followed in all situations. For example the MapControl classes are not checked even though they should only be accessed from the GUI thread. Another example is the IUserProperties.UserProperties property which several classes implement where access to the property itself is checked but access to the returned AttributeSet is not.
Examples
The following examples shows the kinds of errors that will be detected by the thread access verifier.
// Assume the following method is called on the GUI thread.
void ModifyView(View view)
{
// Create a new LayerSet.
var layerSet = new LayerSet();
// Create and add a child layer.
var childLayer = new OrdinaryLayer();
layerSet.Layers.Add(childLayer);
// We can continue and modify layerSet or childLayer without a Guard
// because it has not been added to a View yet so now we create an
// operator chain that draws symbols from a MemoryDataSet.
var dataSet = new MemoryDataSet();
var readOp = new ReadOperator(dataSet);
var visOp = new VisualizationOperator(readOp);
visOp.Visualizers.Add(new SymbolVisualizer());
childLayer.Input = visOp;
// Create a Guard to take the configuration lock.
using (var g = new Guard())
{
// Throws without the Guard.
view.Layers.Add(layerSet);
// Carmenta Engine keeps track of objects that belong to a View
// so the following line will also throw without the Guard.
visOp.Visualizers.Add(new TextVisualizer());
// Carmenta Engine also knows that the ReadOperator at the end
// of the operator chain belongs to a View so the following
// line will also throw without the Guard.
readOp.Query = new Query();
// Remove layerSet from the View.
view.Layers.Remove(layerSet);
}
// layerSet and all elements under it have now been removed from the
// View so the following lines work fine even without a Guard.
readOp.Query = null;
visOp.Input = null;
visOp.Visualizers.Clear();
layerSet.Layers.Clear();
}
Deactivating the Thread Access Verifier
There are two ways to turn off the thread access verifier:
Call View.DisableThreadAccessVerification to turn off all runtime checks for a specific View instance and its configuration elements but keep them active for the rest of the application. One case when this can be useful is if an application uses a background thread to render bitmaps (maybe for printing or some other purpose).
You can also initialize Carmenta Engine by calling one of the Runtime.Initialize overloads that take a boolean verifyThreadAccess parameters and specify False which will turn off the thread access verifier for the entire process.
An application can only deactivate the thread access verifier, it cannot be reactivated at runtime.