Threading model, custom objects
This article contains more details about how the Carmenta Engine threading model affects the implementation of the various custom objects.
Custom objects
Custom objects is a way for an application to provide its own implementation of a dataset, operator, symbol, visualizer or propagation that Carmenta Engine then calls in the same way as a built-in variant of the same type would be called. This means that custom objects can be called on background threads, sometimes by more than one thread simultaneously, which in turn affects their implementation.
Custom datasets
A custom dataset implementation is similar to a MemoryDataSet. It can be accessed on background threads and each custom dataset instance has its own lock that can be used to synchronize access to the dataset and/or any features it contains.
 |
Carmenta Engine will acquire the dataset lock automatically before calling the custom dataset implementation which means that it is not necessary to acquire the lock explicitly in the ICustomDataSet or ICustomRasterDataSet implementations or when overriding a virtual method inherited from the CustomDataSetAdapter class. However, proper synchronization must be taken care of if:
The custom dataset starts its own background threads that updates its internal state. For example, a custom dataset that returns features that represent vehicles and uses a background thread to read new vehicle positions from a communication channel at regular intervals.
The custom dataset has public properties and/or methods that can be called by an application to modify its internal state.
The custom dataset lock is acquired by instantiating the Guard class using the constructor that takes a CustomDataSetContext reference with the context that was passed to the ICustomDataSet.InitNew method. Custom dataset implementations that inherit from the CustomDataSetAdapter class can access the context associated with a custom dataset through the CustomDataSetAdapter.Context property. The lock is released when the Guard is destroyed (or disposed in one of the garbage collected APIs).
Custom operators, symbols, visualizers and propagations
Custom operators, symbols, visualizers and propagations are all called in a similar manner by Carmenta Engine. The main difference between them are listed in the following table:
Object type | Can be called by multiple threads simultaneously? |
|---|---|
Custom operator | No, but can be called by different threads at different times. |
Custom symbol | Yes. |
Custom visualizer | Yes. |
Custom propagation | Yes. |
The best way to ensure that a custom operator, symbol, visualizer or propagation is implemented correctly is to make the implementation stateless (of course read-only data that is initialized once when the custom object is instantiated can be used without problems).
If the custom object can be accessed directly at runtime by an application, for example if it exposes properties or methods that change its behavior, then the application must acquire the configuration lock, described in Threading Model, configuration, before accessing the custom object.
See Also
Reference
Other Resources
Carmenta Engine Threading Model
Threading Model, configuration
Threading Model, datasets and features