org.omg.dds.core.WaitSet Class Reference

A WaitSet object allows an application to wait until one or more of the attached org.omg.dds.core.Condition objects has a triggerValue of true or else until the timeout expires. More...

Inheritance diagram for org.omg.dds.core.WaitSet:

Collaboration diagram for org.omg.dds.core.WaitSet:

Public Member Functions
abstract void	attachCondition (Condition cond)
	This operation attaches a Condition to the WaitSet. More...
abstract void	detachCondition (Condition cond)
	Detaches a Condition from the WaitSet. More...
abstract Collection< Condition >	getConditions ()
	This operation retrieves the list of attached conditions. More...
ServiceEnvironment	getEnvironment ()
abstract void	waitForConditions ()
	This operation allows an application thread to wait for the occurrence of a certain condition. More...
abstract void	waitForConditions (Collection< Condition > activeConditions)
	This operation allows an application thread to wait for the occurrence of certain conditions. More...
abstract void	waitForConditions (Duration timeout) throws TimeoutException
	This operation allows an application thread to wait for the occurrence of certain conditions. More...
abstract void	waitForConditions (long timeout, TimeUnit unit) throws TimeoutException
	This operation allows an application thread to wait for the occurrence of certain conditions. More...
abstract void	waitForConditions (Collection< Condition > activeConditions, Duration timeout) throws TimeoutException
	This operation allows an application thread to wait for the occurrence of certain conditions. More...
abstract void	waitForConditions (Collection< Condition > activeConditions, long timeout, TimeUnit unit) throws TimeoutException
	This operation allows an application thread to wait for the occurrence of certain conditions. More...

Static Public Member Functions
static WaitSet	newWaitSet (ServiceEnvironment env)
	Creates a new WaitSet object to be used in the application. More...

Detailed Description

A WaitSet object allows an application to wait until one or more of the attached org.omg.dds.core.Condition objects has a triggerValue of true or else until the timeout expires.

WaitSet is not necessarily associated with a single org.omg.dds.domain.DomainParticipant and could be used to wait on Condition objects associated with different DomainParticipant objects.

This mechanism is wait-based. Its general use pattern is as follows:

• The application indicates which relevant information it wants to get by creating org.omg.dds.core.Condition objects (org.omg.dds.core.StatusCondition, org.omg.dds.sub.ReadCondition or org.omg.dds.sub.QueryCondition) and attaching them to a WaitSet.
• It then waits on that WaitSet until the triggerValue of one or several Condition objects become true.
• It then uses the result of the wait (i.e., the list of Condition objects with triggerValue == true) to actually get the information by calling:
  • org.omg.dds.core.Entity#getStatusChanges() and then get<CommunicationStatus> on the relevant Entity.
  • org.omg.dds.core.Entity#getStatusChanges() and then org.omg.dds.sub.Subscriber#getDataReaders() on the relevant Subscriber.
  • org.omg.dds.core.Entity#getStatusChanges() and then org.omg.dds.sub.DataReader#read()/ org.omg.dds.sub.DataReader#take() on the relevant DataReader.
  • Directly call org.omg.dds.sub.DataReader#read(org.omg.dds.sub.DataReader.Selector)/ org.omg.dds.sub.DataReader#take(org.omg.dds.sub.DataReader.Selector) with the org.omg.dds.sub.DataReader.Selector wrapping a ReadCondition or a QueryCondition.

Usually the first step is done in an initialization phase, while the others are put in the application main loop.

As there is no extra information passed from the middleware to the application when a wait returns (only the list of triggered Condition objects), Condition objects are meant to embed all that is needed to react properly when enabled. In particular, Entity-related conditions are related to exactly one Entity and cannot be shared.

The blocking behavior of the WaitSet is described below. The result of a waitForConditions() operation depends on the state of the WaitSet, which in turn depends on whether at least one attached Condition has a triggerValue of true. If the waitForConditions() operation is called on WaitSet that is blocked, it will block the calling thread. If waitForConditions() is called on a WaitSet that is unblocked, it will return immediately. In addition, when the WaitSet transitions from BLOCKED to UNBLOCKED it wakes up any threads that had called waitForConditions() on it.

Similar to the invocation of listeners, there is no implied "event queuing" in the awakening of a WaitSet in the sense that, if several Conditions attached to the WaitSet have their triggerValue transition to true in sequence the DCPS implementation needs to only unblock the WaitSet once.

Example

// Instantiate a WaitSet.
WaitSet w = WaitSet.newWaitSet(env);

// Obtain a StatusCondition from a DataReader
StatusCondition<DataReader<Foo>> statusCond = dataReader.getStatusCondition();
// Select the status you are interested in.
statusCond.setEnabledStatuses(InconsistentTopicStatus.class);

// Attach the StatusCondition to the WaitSet.
w.attachCondition(statusCond);
Duration waitTimeout = Duration.newDuration(60, TimeUnit.SECONDS, env);

// Wait for the status to trigger.
try
{
   w.waitForConditions(waitTimeout);
}
catch (TimeoutException e) {
}

Definition at line 117 of file WaitSet.java.

Member Function Documentation

attachCondition()

abstract void org.omg.dds.core.WaitSet.attachCondition ( Condition  cond )

abstract

This operation attaches a Condition to the WaitSet.

The parameter cond must be either a ReadCondition, QueryCondition, StatusCondition or GuardCondition. To get this parameter see:

• org.omg.dds.sub.ReadCondition created by org.omg.dds.sub.DataReader#createReadCondition(org.omg.dds.sub.Subscriber.DataState)
• org.omg.dds.sub.QueryCondition created by org.omg.dds.sub.DataReader#createQueryCondition(String, java.util.List)
• org.omg.dds.core.StatusCondition retrieved by org.omg.dds.core.Entity#getStatusCondition() on an Entity
• org.omg.dds.core.GuardCondition created by org.omg.dds.core.GuardCondition#newGuardCondition(ServiceEnvironment env)

When a GuardCondition is initially created, the triggerValue is false.

It is possible to attach a Condition on a WaitSet that is currently being waited upon (via the waitForConditions() operation). In this case, if the Condition has a triggerValue of true, then attaching the condition will unblock the WaitSet.

Adding a Condition that is already attached to the WaitSet has no effect.

Parameters

cond	The Condition to attach to the WaitSet

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.

detachCondition()

abstract void org.omg.dds.core.WaitSet.detachCondition ( Condition  cond )

abstract

Detaches a Condition from the WaitSet.

Parameters

cond	The Condition to detach from this WaitSet

Exceptions

PreconditionNotMetException	if the Condition was not attached to the WaitSet.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.

getConditions()

abstract Collection<Condition> org.omg.dds.core.WaitSet.getConditions ( )

abstract

This operation retrieves the list of attached conditions.

The list can contain the following conditions:

ReadCondition, QueryCondition, StatusCondition or GuardCondition.

• org.omg.dds.sub.ReadCondition created by org.omg.dds.sub.DataReader#createReadCondition(org.omg.dds.sub.Subscriber.DataState)
• org.omg.dds.sub.QueryCondition created by org.omg.dds.sub.DataReader#createQueryCondition(String, java.util.List)
• org.omg.dds.core.StatusCondition retrieved by org.omg.dds.core.Entity#getStatusCondition() on an Entity
• org.omg.dds.core.GuardCondition created by org.omg.dds.core.GuardCondition#newGuardCondition(ServiceEnvironment env)

Returns

an unmodifiable collection of the conditions attached to this wait set.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.

getEnvironment()

ServiceEnvironment org.omg.dds.core.DDSObject.getEnvironment ( )

inherited

Returns

the org.omg.dds.core.ServiceEnvironment object that directly or indirectly was used to create this object.

Implemented in org.omg.dds.core.ServiceEnvironment, org.opensplice.dds.sub.ReflectionDataReader< TYPE, OUT_TYPE >, org.opensplice.dds.core.ModifiableTimeImpl, org.opensplice.dds.pub.ReflectionDataWriter< TYPE >, org.opensplice.dds.core.DurationImpl, org.opensplice.dds.topic.ContentFilteredTopicImpl< TYPE >, org.opensplice.dds.sub.ReadConditionImpl< TYPE >, org.opensplice.dds.core.EntityQosImpl< T extends QosPolicy >, org.opensplice.dds.type.TypeSupportImpl< TYPE >, org.opensplice.dds.topic.PublicationBuiltinTopicDataImpl, org.opensplice.dds.topic.SubscriptionBuiltinTopicDataImpl, org.opensplice.dds.topic.TopicBuiltinTopicDataImpl, org.opensplice.dds.domain.DomainParticipantFactoryImpl, org.opensplice.dds.core.QosProviderImpl, org.opensplice.dds.core.status.OfferedIncompatibleQosStatusImpl, org.opensplice.dds.core.status.RequestedIncompatibleQosStatusImpl, org.opensplice.dds.core.InstanceHandleImpl, org.opensplice.dds.core.StatusConditionImpl< T extends Entity<?, ?>, org.opensplice.dds.core.status.LivelinessChangedStatusImpl, org.opensplice.dds.core.status.PublicationMatchedStatusImpl, org.opensplice.dds.core.status.SubscriptionMatchedStatusImpl, org.opensplice.dds.sub.SampleImpl< TYPE >, org.opensplice.dds.core.policy.ShareImpl, org.opensplice.dds.core.status.OfferedDeadlineMissedStatusImpl, org.opensplice.dds.core.status.SampleRejectedStatusImpl, org.opensplice.dds.core.WaitSetImpl, org.opensplice.dds.topic.ParticipantBuiltinTopicDataImpl, org.opensplice.dds.core.status.RequestedDeadlineMissedStatusImpl, org.opensplice.dds.topic.BuiltinTopicKeyImpl, org.opensplice.dds.core.GuardConditionImpl, org.opensplice.dds.core.event.AllDataDisposedEventImpl< TYPE >, org.opensplice.dds.core.policy.QosPolicyCountImpl, org.opensplice.dds.core.status.InconsistentTopicStatusImpl, org.opensplice.dds.core.status.LivelinessLostStatusImpl, org.opensplice.dds.core.status.SampleLostStatusImpl, org.opensplice.dds.core.policy.QosPolicyImpl, org.opensplice.dds.core.status.AllDataDisposedStatusImpl, org.opensplice.dds.core.IllegalArgumentExceptionImpl, org.opensplice.dds.core.InconsistentPolicyExceptionImpl, org.opensplice.dds.core.policy.PolicyFactoryImpl, org.opensplice.dds.core.policy.TypeConsistencyEnforcementImpl, org.opensplice.dds.core.PreconditionNotMetExceptionImpl, org.opensplice.dds.core.AlreadyClosedExceptionImpl, org.opensplice.dds.core.IllegalOperationExceptionImpl, org.opensplice.dds.core.ImmutablePolicyExceptionImpl, org.opensplice.dds.core.NotEnabledExceptionImpl, org.opensplice.dds.core.OutOfResourcesExceptionImpl, org.opensplice.dds.core.DDSExceptionImpl, org.opensplice.dds.core.status.DataAvailableStatusImpl, and org.opensplice.dds.core.status.DataOnReadersStatusImpl.

newWaitSet()

static WaitSet org.omg.dds.core.WaitSet.newWaitSet ( ServiceEnvironment  env )

static

Creates a new WaitSet object to be used in the application.

Parameters

env	Identifies the Service instance to which the new object will belong.

Definition at line 127 of file WaitSet.java.

waitForConditions() [1/6]

abstract void org.omg.dds.core.WaitSet.waitForConditions ( )

abstract

This operation allows an application thread to wait for the occurrence of a certain condition.

If the condition attached to the WaitSet does not a triggerValue of true, the operation will block suspending the calling thread.

The operation will unblock when the attached condition has a triggerValue of true.

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the operation is invoked on a WaitSet that already has a thread blocking on it, the operation will fail with the value org.omg.dds.core.PreconditionNotMetException.

Exceptions

org.omg.dds.core.PreconditionNotMetException	The WaitSet already has an application thread blocking on it.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.

waitForConditions() [2/6]

abstract void org.omg.dds.core.WaitSet.waitForConditions ( Collection< Condition >  activeConditions )

abstract

This operation allows an application thread to wait for the occurrence of certain conditions.

If none of the conditions attached to the WaitSet have a triggerValue of true, the operation will block suspending the calling thread.

The result of the wait operation is the list of all the attached conditions that have a triggerValue of true (i.e., the conditions that unblocked the wait).

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the operation is invoked on a WaitSet that already has a thread blocking on it, the operation will fail with the value org.omg.dds.core.PreconditionNotMetException.

Parameters

activeConditions

a collection where the triggered conditions are stored in.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.PreconditionNotMetException	The WaitSet already has an application thread blocking on it.

waitForConditions() [3/6]

abstract void org.omg.dds.core.WaitSet.waitForConditions ( Duration  timeout ) throws TimeoutException

abstract

This operation allows an application thread to wait for the occurrence of certain conditions.

If none of the conditions attached to the WaitSet have a triggerValue of true, the operation will block suspending the calling thread.

The operation will unblock when the attached condition has a triggerValue of true or when the timeout period has elapsed a TimeoutException occurs.

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the operation is invoked on a WaitSet that already has a thread blocking on it, the operation will fail with the value org.omg.dds.core.PreconditionNotMetException.

Parameters

timeout

The maximum duration to block for the wait, after which the application thread is unblocked.

Exceptions

TimeoutException	if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.PreconditionNotMetException	The WaitSet already has an application thread blocking on it.

waitForConditions() [4/6]

abstract void org.omg.dds.core.WaitSet.waitForConditions ( long  timeout, TimeUnit  unit  ) throws TimeoutException

abstract

This operation allows an application thread to wait for the occurrence of certain conditions.

If none of the conditions attached to the WaitSet have a triggerValue of true, the operation will block suspending the calling thread.

The operation will unblock when the attached condition has a triggerValue of true or when the timeout period has elapsed a TimeoutException occurs.

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the operation is invoked on a WaitSet that already has a thread blocking on it, the operation will fail with the value org.omg.dds.core.PreconditionNotMetException.

Parameters

timeout	The maximum duration to block for the wait, after which the application thread is unblocked.
unit	The TimeUnit which the timeout describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

TimeoutException	if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.PreconditionNotMetException	The WaitSet already has an application thread blocking on it.

waitForConditions() [5/6]

abstract void org.omg.dds.core.WaitSet.waitForConditions ( Collection< Condition >  activeConditions, Duration  timeout  ) throws TimeoutException

abstract

This operation allows an application thread to wait for the occurrence of certain conditions.

If none of the conditions attached to the WaitSet have a triggerValue of true, the operation will block suspending the calling thread.

The result of the wait operation is the list of all the attached conditions that have a triggerValue of true (i.e., the conditions that unblocked the wait).

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the operation is invoked on a WaitSet that already has a thread blocking on it, the operation will fail with the value org.omg.dds.core.PreconditionNotMetException.

Parameters

activeConditions	a collection where the triggered conditions are stored in.
timeout	The maximum duration to block for the wait, after which the application thread is unblocked.

Exceptions

TimeoutException	if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.PreconditionNotMetException	The WaitSet already has an application thread blocking on it.

waitForConditions() [6/6]

abstract void org.omg.dds.core.WaitSet.waitForConditions ( Collection< Condition >  activeConditions, long  timeout, TimeUnit  unit  ) throws TimeoutException

abstract

This operation allows an application thread to wait for the occurrence of certain conditions.

If none of the conditions attached to the WaitSet have a triggerValue of true, the operation will block suspending the calling thread.

The result of the wait operation is the list of all the attached conditions that have a triggerValue of true (i.e., the conditions that unblocked the wait).

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the operation is invoked on a WaitSet that already has a thread blocking on it, the operation will fail with the value org.omg.dds.core.PreconditionNotMetException.

Parameters

activeConditions	a collection where the triggered conditions are stored in.
timeout	The maximum duration to block for the wait, after which the application thread is unblocked.
unit	The TimeUnit which the timeout describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

TimeoutException	if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.PreconditionNotMetException	The WaitSet already has an application thread blocking on it.

---

The documentation for this class was generated from the following file:

• java5/common/java/code/org/omg/dds/core/WaitSet.java