ExclusiveAreaQosPolicy Class Reference

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

Inheritance diagram for ExclusiveAreaQosPolicy:

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.
Public Attributes inherited from QosPolicy
final QosPolicyId_t	id
	The ID of this QoS policy.
final String	policy_name
	The name of this QoS policy.

Additional Inherited Members
Public Member Functions inherited from Struct
abstract boolean	equals (Object obj)
abstract int	hashCode ()
String	toString ()
Protected Member Functions inherited from Struct
	Struct ()
abstract void	pull_from_nativeI (long native_status)
abstract void	push_to_nativeI (long native_status)

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 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.

Entity:

com.rti.dds.publication.Publisher, com.rti.dds.subscription.Subscriber

Properties:

RxO = N/A
Changeable = NO

See Also

com.rti.dds.infrastructure.Listener

Usage

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 Chapter 4 in the User's Manual for complete documentation on Exclusive Areas.

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.

Member Data Documentation

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