RTI Connext Java API
Version 7.0.0
|
Configures multi-thread concurrency and deadlock prevention capabilities. More...
Public Attributes | |
boolean | use_shared_exclusive_area |
Whether the com.rti.dds.infrastructure.Entity is protected by its own exclusive area or the shared exclusive area. More... | |
![]() | |
final QosPolicyId_t | id |
The ID of this QoS policy. More... | |
final String | policy_name |
The name of this QoS policy. More... | |
Configures multi-thread concurrency and deadlock prevention capabilities.
An "exclusive area" is an abstraction of a multi-thread-safe region. Each entity is protected by one and only one exclusive area, although a single exclusive area may be shared by multiple entities.
Conceptually, an exclusive area is a mutex or monitor with additional deadlock protection features. If a com.rti.dds.infrastructure.Entity has "entered" its exclusive area to perform a protected operation, no other com.rti.dds.infrastructure.Entity sharing the same exclusive area may enter it until the first com.rti.dds.infrastructure.Entity "exits" the exclusive area.
Exclusive Areas (EAs) allow RTI Connext to be multi-threaded while preventing deadlock in multi-threaded applications. EAs prevent a com.rti.dds.domain.DomainParticipant object's internal threads from deadlocking with each other when executing internal code as well as when executing the code of user-registered listener callbacks.
Within an EA, all calls to the code protected by the EA are single threaded. Each com.rti.dds.domain.DomainParticipant, com.rti.dds.publication.Publisher and com.rti.dds.subscription.Subscriber entity represents a separate EA. Thus all DataWriters of the same Publisher and all DataReaders of the same Subscriber share the EA of its parent. Note: this means that operations on the DataWriters of the same Publisher and on the DataReaders of the same Subscriber will be serialized, even when invoked from multiple concurrent application threads.
Within an EA, there are limitations on how code protected by a different EA can be accessed. For example, when received data is being processed by user code in the DataReader Listener, within a Subscriber EA, the user code may call the com.rti.ndds.example.FooDataWriter.write operation of a DataWriter that is protected by the EA of its Publisher, so you can send data in the function called to process received data. However, you cannot create entities or call functions that are protected by the EA of the com.rti.dds.domain.DomainParticipant. See the "Exclusive Areas (EAs)" section in the User's Manual for more information.
With this QoS policy, you can force a com.rti.dds.publication.Publisher or com.rti.dds.subscription.Subscriber to share the same EA as its com.rti.dds.domain.DomainParticipant. Using this capability, the restriction of not being able to create entities in a DataReader Listener's on_data_available() callback is lifted. However, the tradeoff is that the application has reduced concurrency through the Entities that share an EA.
Note that the restrictions on calling methods in a different EA only exist for user code that is called in registered DDS Listeners by internal DomainParticipant threads. User code may call all RTI Connext functions for any DDS Entities from their own threads at any time.
boolean use_shared_exclusive_area |
Whether the com.rti.dds.infrastructure.Entity is protected by its own exclusive area or the shared exclusive area.
All writers belonging to the same com.rti.dds.publication.Publisher are protected by the same exclusive area as the com.rti.dds.publication.Publisher itself. The same is true of all readers belonging to the same com.rti.dds.subscription.Subscriber. Typically, the publishers and subscribers themselves do not share their exclusive areas with each other; each has its own. This configuration maximizes the concurrency of the system because independent readers and writers do not need to take the same mutexes in order to operate. However, it places some restrictions on the operations that may be invoked from within listener callbacks because of the possibility of a deadlock. See the com.rti.dds.infrastructure.Listener documentation for more details.
If this field is set to com.rti.dds.infrastructure.false, the default more concurrent behavior will be used. In the event that this behavior is insufficiently flexible for your application, you may set this value to com.rti.dds.infrastructure.true. In that case, the com.rti.dds.subscription.Subscriber or com.rti.dds.publication.Publisher in question, and all of the readers or writers (as appropriate) created from it, will share a global exclusive area. This global exclusive area is shared by all entities whose value for this QoS field is com.rti.dds.infrastructure.true. By sharing the same exclusive area across a larger number of entities, the concurrency of the system will be decreased; however, some of the callback restrictions will be relaxed.
[default] com.rti.dds.infrastructure.false