RTI Connext Modern C++ API  Version 6.1.0
rti::core::policy::ExclusiveArea Class Reference

<<extension>> Configures multi-threading and deadlock prevention More...

#include <rti/core/policy/CorePolicy.hpp>

Public Member Functions

 ExclusiveArea ()
 Creates the default policy. More...
 
 ExclusiveArea (bool the_use_shared_exclusive_area)
 Creates an instance specifying the use of shared or exclusive area. More...
 
ExclusiveAreause_shared_exclusive_area (bool the_use_shared_exclusive_area)
 Whether the dds::core::Entity is protected by its own exclusive area or the shared one. More...
 
bool use_shared_exclusive_area () const
 Getter (see setter with the same name) More...
 

Static Public Member Functions

static ExclusiveArea SharedEA ()
 Returns ExclusiveArea(true) More...
 
static ExclusiveArea ExclusiveEA ()
 Returns ExclusiveArea(false) More...
 

Detailed Description

<<extension>> Configures multi-threading and deadlock prevention

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

Entity:
dds::pub::Publisher, dds::sub::Subscriber
Properties:
RxO = N/A
Changeable = NO
See also
Listener

Usage

Exclusive Areas (EAs) allow RTI Connext to be multi-threaded while preventing deadlock in multi-threaded applications. EAs prevent a 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 dds::domain::DomainParticipant, dds::pub::Publisher and dds::sub::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 dds::pub::DataWriter::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::domain::DomainParticipant. See the "Exclusive Areas (EAs)" section in the User's Manual for more information.

With this QoS policy, you can force a dds::pub::Publisher or dds::sub::Subscriber to share the same EA as its 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.

Constructor & Destructor Documentation

◆ ExclusiveArea() [1/2]

rti::core::policy::ExclusiveArea::ExclusiveArea ( )
inline

Creates the default policy.

◆ ExclusiveArea() [2/2]

rti::core::policy::ExclusiveArea::ExclusiveArea ( bool  the_use_shared_exclusive_area)
inlineexplicit

Creates an instance specifying the use of shared or exclusive area.

See use_shared_exclusive_area().

Member Function Documentation

◆ SharedEA()

static ExclusiveArea rti::core::policy::ExclusiveArea::SharedEA ( )
inlinestatic

Returns ExclusiveArea(true)

◆ ExclusiveEA()

static ExclusiveArea rti::core::policy::ExclusiveArea::ExclusiveEA ( )
inlinestatic

Returns ExclusiveArea(false)

◆ use_shared_exclusive_area() [1/2]

ExclusiveArea& rti::core::policy::ExclusiveArea::use_shared_exclusive_area ( bool  the_use_shared_exclusive_area)

Whether the dds::core::Entity is protected by its own exclusive area or the shared one.

All writers belonging to the same dds::pub::Publisher are protected by the same exclusive area as the dds::pub::Publisher itself. The same is true of all readers belonging to the same dds::sub::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 Listener documentation for more details.

If this field is set to 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 true. In that case, the dds::sub::Subscriber or dds::pub::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 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] false

◆ use_shared_exclusive_area() [2/2]

bool rti::core::policy::ExclusiveArea::use_shared_exclusive_area ( ) const

Getter (see setter with the same name)