46.3 EXCLUSIVE_AREA QosPolicy (DDS Extension)

This QoSPolicy is deprecated as of release 6.1.1 and will be removed in a future release.

This QosPolicy controls the creation and use of Exclusive Areas. An exclusive area (EA) is a mutex with built-in deadlock protection when multiple EAs are in use. It is used to provide mutual exclusion among different threads of execution. Multiple EAs allow greater concurrency among the internal and user threads when executing Connext code.

EAs allow Connext to be multi-threaded while preventing threads from a classical deadlock scenario for multi-threaded applications. EAs prevent a DomainParticipant'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 DomainParticipant, Publisher and Subscriber represents a separate EA. All DataWriters of the same Publisher and all DataReaders of the same Subscriber share the EA of its parent. This means that the DataWriters of the same Publisher and the DataReaders of the same Subscriber are inherently single threaded.

Within an EA, there are limitations on how code protected by a different EA can be accessed. For example, when data is being processed by user code received in the DataReaderListener of a Subscriber EA, the user code may call the write() function 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 DomainParticipant. See 15.8.8 Exclusive Areas (EAs) for the complete documentation on Exclusive Areas.

With this QoS, you can force a Publisher or Subscriber to share the same EA as its DomainParticipant. Using this capability, the restriction of not being to create Entities in a DataReaderListener's on_data_available() callback is lifted. However, the trade-off 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 exists for user code that is called in registered Listeners by internal DomainParticipant threads. User code may call all Connext functions for any Entities from their own threads at any time.

The EXCLUSIVE_AREA includes a single member, as listed in Table 46.3 DDS_ExclusiveAreaQosPolicy. For the default value, please see the API Reference HTML documentation.

The implications and restrictions of using a private or shared EA are discussed in 15.8.8 Exclusive Areas (EAs). The basic trade-off is concurrency versus restrictions on which methods can be called in user, listener, callback functions. To summarize:

Behavior when the Publisher or Subscriber’s use_shared_exclusive_area is set to FALSE:

• The creation of the Publisher/Subscriber will create an EA that will be used only by the Publisher/Subscriber and the DataWriters/DataReaders that belong to them.
• Consequences: This setting maximizes concurrency at the expense of creating a mutex for the Publisher or Subscriber. In addition, using a separate EA may restrict certain Connext operations (see 15.8.6 Operations Allowed within Listener Callbacks) from being called from the callbacks of Listeners attached to those Entities and the Entities that they create. This limitation results from a built-in deadlock protection mechanism.

Behavior when the Publisher or Subscriber’s use_shared_exclusive_area is set to TRUE:

• The creation of the Publisher/Subscriber does not create a new EA. Instead, the Publisher/Subscriber, along with the DataWriters/DataReaders that they create, will use a common EA shared with the DomainParticipant.
• Consequences: By sharing the same EA among multiple Entities, you may decrease the amount of concurrency in the application, which can adversely impact performance. However, this setting does use less resources and allows you to call almost any operation on any Entity within a listener callback (see 15.8.8 Exclusive Areas (EAs) for full details).

46.3.1 Example

The code in Figure 46.2: Creating a Publisher with a Shared Exclusive Area illustrates how to change the EXCLUSIVE_AREA policy.

Note:

• In C, you must initialize the QoS structures before they are used, see 42.2 Special QosPolicy Handling Considerations for C.

DDS_PublisherQos publisher_qos;

// domain, publisher_listener have been previously created
if (participant->get_default_publisher_qos(publisher_qos) !=
    DDS_RETCODE_OK) {
    // handle error
}

publisher_qos.exclusive_area.use_shared_exclusive_area = DDS_BOOLEAN_TRUE;
DDSPublisher* publisher = participant->create_publisher(publisher_qos,
    publisher_listener, DDS_STATUS_MASK_ALL);

46.3.2 Properties

This QosPolicy cannot be modified after the Entity has been created.

It can be set differently on the publishing and subscribing sides.

46.3.3 Related QosPolicies

This QosPolicy does not interact with any other policies.

46.3.4 Applicable DDS Entities

• 30. Publishers
• 39. Subscribers

46.3.5 System Resource Considerations

This QosPolicy affects the use of operating-system mutexes. When use_shared_exclusive_area is FALSE, the creation of a Publisher or Subscriber will create an operating-system mutex.