Changes due to the new threading model
This article describes the areas of a Carmenta Engine 4.x application that might have to be modified to run correctly under the new threading model in Carmenta Engine 5.
For more details about the new threading model see Carmenta Engine Threading Model.
Working with views
Methods and properties on View and GlobeView can only be called reliably from the GUI thread of the application unless specified otherwise by the documentation.
Events
Events can be fired from background threads which means that event handlers cannot assume they are running on a specific thread and they might need to marshal the call to another thread to handle the event correctly.
The following table lists the Carmenta Engine 4.x events and their Carmenta Engine 5 counterparts that should be verified.
Carmenta Engine 4.x | Carmenta Engine 5 |
|---|---|
SpaceX.Error | |
SpaceX.GlobalStatus |
In addition to the events listed in the table above Carmenta Engine 5 also adds several new events to various classes, please see the documentation for each event for specific thread safety information.
Using MemoryDataSet
The MemoryDataSet replaces the Carmenta Engine 4.x class InternalStore as an in-memory data set that holds application objects. A major change in Carmenta Engine 5 is that MemoryDataSet provides synchronization operations, through the Guard class, that makes it possible to safely use a MemoryDataSet in configurations that load data in background threads or to modify features from background threads. This also means that you must add explicit locking in your application code for it to work correctly.
For more details see Migrating code using InternalStore.
Modifying the configuration at runtime
Code that modifies a configuration at runtime, whether building it from scratch or simply setting new values on some properties, must synchronize access to the configuration with other threads that can be accessing the configuration. This is done by making use of the Guard class.
// Lock the configuration so we can modify it safely
using (Guard g = new Guard())
visualizer.Color = System.Drawing.Color.AliceBlue;
Custom objects
Like in Carmenta Engine 4.x custom objects can be called on background threads and the custom object implementations cannot assume they are running on a specific thread.