RTI Connext C++ API  Version 5.1.0
DDS_ExclusiveAreaQosPolicy Struct Reference

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

Public Attributes

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

Entity:
DDSPublisher, DDSSubscriber
Properties:
RxO = N/A
Changeable = NO
See Also
DDSListener

Usage

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

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

Member Data Documentation

DDS_Boolean DDS_ExclusiveAreaQosPolicy::use_shared_exclusive_area

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

All writers belonging to the same DDSPublisher are protected by the same exclusive area as the DDSPublisher itself. The same is true of all readers belonging to the same DDSSubscriber. 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 DDSListener 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 DDSSubscriber or DDSPublisher 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


RTI Connext C++ API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc