DDS_ExclusiveAreaQosPolicy Struct Reference

Configures multi-thread concurrency and deadlock prevention capabilities. More...

Data Fields
DDS_Boolean	use_shared_exclusive_area
	Whether the DDS_Entity is protected by its own exclusive area or the shared exclusive area.

Detailed Description

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 DDS_Entity has "entered" its exclusive area to perform a protected operation, no other DDS_Entity sharing the same exclusive area may enter it until the first DDS_Entity "exits" the exclusive area.

Entity:

DDS_Publisher, DDS_Subscriber

Properties:

RxO = N/A
Changeable = NO

See Also

DDS_Listener

Usage

Exclusive Areas (EAs) allow RTI Connext to be multi-threaded while preventing deadlock in multi-threaded applications. EAs prevent a DDS_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 DDS_DomainParticipant, DDS_Publisher and DDS_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 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 DDS_DomainParticipant. See Chapter 4 in the User's Manual for complete documentation on Exclusive Areas.

With this QoS policy, you can force a DDS_Publisher or DDS_Subscriber to share the same EA as its DDS_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.

Field Documentation

DDS_Boolean DDS_ExclusiveAreaQosPolicy::use_shared_exclusive_area

Whether the DDS_Entity is protected by its own exclusive area or the shared exclusive area.

All writers belonging to the same DDS_Publisher are protected by the same exclusive area as the DDS_Publisher itself. The same is true of all readers belonging to the same DDS_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 DDS_Listener documentation for more details.

If this field is set to DDS_BOOLEAN_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 DDS_BOOLEAN_TRUE. In that case, the DDS_Subscriber or DDS_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 DDS_BOOLEAN_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] DDS_BOOLEAN_FALSE