org.omg.dds.core

Class WaitSet

java.lang.Object

org.omg.dds.core.WaitSet

All Implemented Interfaces:

DDSObject

public abstract class WaitSet
extends Object
implements DDSObject

A WaitSet object allows an application to wait until one or more of the attached Condition objects has a triggerValue of true or else until the timeout expires. WaitSet is not necessarily associated with a single 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 Condition objects (StatusCondition, ReadCondition or 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:
  • Entity.getStatusChanges() and then get<CommunicationStatus> on the relevant Entity.
  • Entity.getStatusChanges() and then Subscriber.getDataReaders(Collection) on the relevant Subscriber.
  • Entity.getStatusChanges() and then DataReader.read()/ DataReader.take() on the relevant DataReader.
  • Directly call DataReader.read(org.omg.dds.sub.DataReader.Selector)/ DataReader.take(org.omg.dds.sub.DataReader.Selector) with the 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.

Constructor Summary

Constructors

Constructor and Description
WaitSet()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	attachCondition(Condition cond) Attaches a Condition to the WaitSet.
abstract void	detachCondition(Condition cond) Detaches a Condition from the WaitSet.
abstract Collection<Condition>	getConditions() This operation retrieves the list of attached conditions.
static WaitSet	newWaitSet(ServiceEnvironment env)
abstract void	waitForConditions() This operation allows an application thread to wait for the occurrence of certain conditions.
abstract void	waitForConditions(Collection<Condition> activeConditions) This operation allows an application thread to wait for the occurrence of certain conditions.
abstract void	waitForConditions(Collection<Condition> activeConditions, Duration timeout) This operation allows an application thread to wait for the occurrence of certain conditions.
abstract void	waitForConditions(Collection<Condition> activeConditions, long timeout, TimeUnit unit) This operation allows an application thread to wait for the occurrence of certain conditions.
abstract void	waitForConditions(Duration timeout) This operation allows an application thread to wait for the occurrence of certain conditions.
abstract void	waitForConditions(long timeout, TimeUnit unit) This operation allows an application thread to wait for the occurrence of certain conditions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.omg.dds.core.DDSObject

getEnvironment

Constructor Detail

WaitSet

public WaitSet()

Method Detail

newWaitSet

public static WaitSet newWaitSet(ServiceEnvironment env)

Parameters:

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

waitForConditions

public abstract void waitForConditions()

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

waitForConditions

public abstract void waitForConditions(Collection<Condition> activeConditions)

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

waitForConditions

public abstract void waitForConditions(Duration timeout)
                                throws TimeoutException

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

Throws:

TimeoutException - if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.

waitForConditions

public abstract void waitForConditions(long timeout,
                     TimeUnit unit)
                                throws TimeoutException

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

Throws:

TimeoutException - if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.

waitForConditions

public abstract void waitForConditions(Collection<Condition> activeConditions,
                     Duration timeout)
                                throws TimeoutException

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

Throws:

TimeoutException - if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.

waitForConditions

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

Throws:

TimeoutException - if the timeout argument, which specifies the maximum duration for the wait, is exceeded and none of the attached Condition objects is true.

attachCondition

public abstract void attachCondition(Condition cond)

Attaches a Condition to the WaitSet. 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.

Throws:

OutOfResourcesException - if attaching the condition requires the allocation of unavailable middleware or OS resources.

detachCondition

public abstract void detachCondition(Condition cond)

Detaches a Condition from the WaitSet.

Throws:

PreconditionNotMetException - if the Condition was not attached to the WaitSet.

getConditions

public abstract Collection<Condition> getConditions()

This operation retrieves the list of attached conditions.

Returns:

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