RTI Connext Java API  Version 5.1.0
WaitSet Class Reference

<<interface>> Allows an application to wait until one or more of the attached com.rti.dds.infrastructure.Condition objects has a trigger_value of com.rti.dds.infrastructure.true or else until the timeout expires. More...

Inherits AbstractNativeObject.

Public Member Functions

 WaitSet ()
 Default no-argument constructor.
 
 WaitSet (WaitSetProperty_t prop)
 <<eXtension>> Constructor for a com.rti.dds.infrastructure.WaitSet that may delay for more while specifying that will be woken up after the given number of events or delay period, whichever happens first
 
void wait (ConditionSeq active_conditions, Duration_t timeout)
 Allows an application thread to wait for the occurrence of certain conditions.
 
void attach_condition (Condition cond)
 Attaches a com.rti.dds.infrastructure.Condition to the com.rti.dds.infrastructure.WaitSet.
 
void detach_condition (Condition cond)
 Detaches a com.rti.dds.infrastructure.Condition from the com.rti.dds.infrastructure.WaitSet.
 
void get_conditions (ConditionSeq attached_conditions)
 Retrieves the list of attached com.rti.dds.infrastructure.Condition (s).
 
void set_property (WaitSetProperty_t prop)
 <<eXtension>> Sets the com.rti.dds.infrastructure.WaitSetProperty_t, to configure the associated com.rti.dds.infrastructure.WaitSet to return after one or more trigger events have occurred.
 
void get_property (WaitSetProperty_t prop)
 <<eXtension>> Retrieves the com.rti.dds.infrastructure.WaitSetProperty_t configuration of the associated com.rti.dds.infrastructure.WaitSet.
 
void delete ()
 Destructor.
 
- Public Member Functions inherited from AbstractNativeObject
final void check_aliveI ()
 
- Public Member Functions inherited from NativeObject
long get_native_pointer ()
 
void clear_native_pointer ()
 
boolean is_alive ()
 

Additional Inherited Members

- Static Public Member Functions inherited from AbstractNativeObject
static void check_for_zeroI (long native_pointer)
 
static final void check_aliveI (NativeObject obj)
 
static final boolean is_aliveI (NativeObject obj)
 
- Protected Member Functions inherited from AbstractNativeObject
void set_native_pointer (long native_pointer)
 
 AbstractNativeObject (long native_pointer)
 
final void check_for_null_argumentI (Object arg)
 

Detailed Description

<<interface>> Allows an application to wait until one or more of the attached com.rti.dds.infrastructure.Condition objects has a trigger_value of com.rti.dds.infrastructure.true or else until the timeout expires.

Usage

com.rti.dds.infrastructure.Condition (s) (in conjunction with wait-sets) provide an alternative mechanism to allow the middleware to communicate communication status changes (including arrival of data) to the application.

DDSWaitSetConditions.png
com.rti.dds.infrastructure.WaitSet and com.rti.dds.infrastructure.Condition (s)

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

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 com.rti.dds.infrastructure.Condition objects), com.rti.dds.infrastructure.Condition objects are meant to embed all that is needed to react properly when enabled. In particular, com.rti.dds.infrastructure.Entity-related conditions are related to exactly one com.rti.dds.infrastructure.Entity and cannot be shared.

The blocking behavior of the com.rti.dds.infrastructure.WaitSet is illustrated below.

DDSWaitSetBlocking.png
com.rti.dds.infrastructure.WaitSet blocking behavior

The result of a com.rti.dds.infrastructure.WaitSet.WaitSet.wait operation depends on the state of the com.rti.dds.infrastructure.WaitSet, which in turn depends on whether at least one attached com.rti.dds.infrastructure.Condition has a trigger_value of com.rti.dds.infrastructure.true. If the wait operation is called on com.rti.dds.infrastructure.WaitSet with state BLOCKED, it will block the calling thread. If wait is called on a com.rti.dds.infrastructure.WaitSet with state UNBLOCKED, it will return immediately. In addition, when the com.rti.dds.infrastructure.WaitSet transitions from BLOCKED to UNBLOCKED it wakes up any threads that had called wait on it.

A key aspect of the com.rti.dds.infrastructure.Condition/com.rti.dds.infrastructure.WaitSet mechanism is the setting of the trigger_value of each com.rti.dds.infrastructure.Condition.

Trigger State of a com.rti.dds.infrastructure.StatusCondition

The trigger_value of a com.rti.dds.infrastructure.StatusCondition is the boolean OR of the ChangedStatusFlag of all the communication statuses (see Status Kinds) to which it is sensitive. That is, trigger_value == com.rti.dds.infrastructure.false only if all the values of the ChangedStatusFlags are com.rti.dds.infrastructure.false.

The sensitivity of the com.rti.dds.infrastructure.StatusCondition to a particular communication status is controlled by the list of enabled_statuses set on the condition by means of the com.rti.dds.infrastructure.StatusCondition.set_enabled_statuses operation.

Once the trigger_value of a StatusCondition becomes true, it remains true until the status that changed is reset. To reset a status, call the related get_*_status() operation. Or, in the case of the data available status, call read(), take(), or one of their variants. Therefore, if you are using a com.rti.dds.infrastructure.StatusCondition on a com.rti.dds.infrastructure.WaitSet to be notified of events, your thread will wake up when one of the statuses associated with the StatusCondition becomes true. If you do not reset the status, the StatusCondition trigger_value remains true and your WaitSet will not block again; it will immediately wake up when you call com.rti.dds.infrastructure.WaitSet.WaitSet.wait.

Trigger State of a com.rti.dds.subscription.ReadCondition

Similar to the com.rti.dds.infrastructure.StatusCondition, a com.rti.dds.subscription.ReadCondition also has a trigger_value that determines whether the attached com.rti.dds.infrastructure.WaitSet is BLOCKED or UNBLOCKED. However, unlike the com.rti.dds.infrastructure.StatusCondition, the trigger_value of the com.rti.dds.subscription.ReadCondition is tied to the presence of at least a sample managed by RTI Connext with com.rti.dds.subscription.SampleStateKind and com.rti.dds.subscription.ViewStateKind matching those of the com.rti.dds.subscription.ReadCondition. Furthermore, for the com.rti.dds.subscription.QueryCondition to have a trigger_value == com.rti.dds.infrastructure.true, the data associated with the sample must be such that the query_expression evaluates to com.rti.dds.infrastructure.true.

The fact that the trigger_value of a com.rti.dds.subscription.ReadCondition depends on the presence of samples on the associated com.rti.dds.subscription.DataReader implies that a single take operation can potentially change the trigger_value of several com.rti.dds.subscription.ReadCondition or com.rti.dds.subscription.QueryCondition conditions. For example, if all samples are taken, any com.rti.dds.subscription.ReadCondition and com.rti.dds.subscription.QueryCondition conditions associated with the com.rti.dds.subscription.DataReader that had their trigger_value==TRUE before will see the trigger_value change to FALSE. Note that this does not guarantee that com.rti.dds.infrastructure.WaitSet objects that were separately attached to those conditions will not be woken up. Once we have trigger_value==TRUE on a condition, it may wake up the attached com.rti.dds.infrastructure.WaitSet, the condition transitioning to trigger_value==FALSE does not necessarily 'unwakeup' the WaitSet as 'unwakening' may not be possible in general.

The consequence is that an application blocked on a com.rti.dds.infrastructure.WaitSet may return from the wait with a list of conditions, some of which are not no longer 'active'. This is unavoidable if multiple threads are concurrently waiting on separate com.rti.dds.infrastructure.WaitSet objects and taking data associated with the same com.rti.dds.subscription.DataReader entity.

To elaborate further, consider the following example: A com.rti.dds.subscription.ReadCondition that has a sample_state_mask = {com.rti.dds.subscription.SampleStateKind.SampleStateKind.NOT_READ_SAMPLE_STATE} will have trigger_value of com.rti.dds.infrastructure.true whenever a new sample arrives and will transition to com.rti.dds.infrastructure.false as soon as all the newly-arrived samples are either read (so their sample state changes to READ) or taken (so they are no longer managed by RTI Connext). However if the same com.rti.dds.subscription.ReadCondition had a sample_state_mask = { com.rti.dds.subscription.SampleStateKind.SampleStateKind.READ_SAMPLE_STATE, com.rti.dds.subscription.SampleStateKind.SampleStateKind.NOT_READ_SAMPLE_STATE }, then the trigger_value would only become com.rti.dds.infrastructure.false once all the newly-arrived samples are taken (it is not sufficient to read them as that would only change the sample state to READ), which overlaps the mask on the com.rti.dds.subscription.ReadCondition.

Trigger State of a com.rti.dds.infrastructure.GuardCondition

The trigger_value of a com.rti.dds.infrastructure.GuardCondition is completely controlled by the application via the operation com.rti.dds.infrastructure.GuardCondition.set_trigger_value.

Important: The com.rti.dds.infrastructure.WaitSet allocates native resources. When com.rti.dds.infrastructure.WaitSet is no longer being used, user should call com.rti.dds.infrastructure.WaitSet.WaitSet.delete explicitly to properly cleanup all native resources.

See Also
Status Kinds
com.rti.dds.infrastructure.StatusCondition, com.rti.dds.infrastructure.GuardCondition
com.rti.dds.infrastructure.Listener

Constructor & Destructor Documentation

WaitSet ( )

Default no-argument constructor.

Construct a new com.rti.dds.infrastructure.WaitSet.

Important: The com.rti.dds.infrastructure.WaitSet allocates native resources. When the com.rti.dds.infrastructure.WaitSet is no longer being used, users should call com.rti.dds.infrastructure.WaitSet.WaitSet.delete explicitly to properly clean up all native resources.

Exceptions
com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCESif a new com.rti.dds.infrastructure.WaitSet could not be allocated.

<<eXtension>> Constructor for a com.rti.dds.infrastructure.WaitSet that may delay for more while specifying that will be woken up after the given number of events or delay period, whichever happens first

Constructs a new com.rti.dds.infrastructure.WaitSet.

Important: The com.rti.dds.infrastructure.WaitSet allocates native resources. When the com.rti.dds.infrastructure.WaitSet is no longer being used, users should call com.rti.dds.infrastructure.WaitSet.WaitSet.delete explicitly to properly clean up all native resources.

Parameters
prop<<in>> Property of wait set controlling when the wait set should be woken up
Exceptions
com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCESif a new com.rti.dds.infrastructure.WaitSet could not be allocated.

Member Function Documentation

void wait ( ConditionSeq  active_conditions,
Duration_t  timeout 
)

Allows an application thread to wait for the occurrence of certain conditions.

If none of the conditions attached to the com.rti.dds.infrastructure.WaitSet have a trigger_value of com.rti.dds.infrastructure.true, the wait operation will block, suspending the calling thread.

The result of the wait operation is the list of all the attached conditions that have a trigger_value of com.rti.dds.infrastructure.true (i.e., the conditions that unblocked the wait).

Note: The resolution of the timeout period is constrained by the resolution of the system clock.

The wait operation takes a timeout argument that specifies the maximum duration for the wait. If this duration is exceeded and none of the attached com.rti.dds.infrastructure.Condition objects are com.rti.dds.infrastructure.true, wait will throw an exception of com.rti.dds.infrastructure.RETCODE_TIMEOUT. In this case, the resulting list of conditions will be empty.

Note: The resolution of the timeout period is constrained by the resolution of the system clock.

com.rti.dds.infrastructure.RETCODE_TIMEOUT will not be thrown when the timeout duration is exceeded if attached com.rti.dds.infrastructure.Condition objects are com.rti.dds.infrastructure.true, or in the case of a com.rti.dds.infrastructure.WaitSet waiting for more than one trigger event, if one or more trigger events have occurred.

It is not allowable for more than one application thread to be waiting on the same com.rti.dds.infrastructure.WaitSet. If the wait operation is invoked on a com.rti.dds.infrastructure.WaitSet that already has a thread blocking on it, the operation will return immediately with the value com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

Parameters
active_conditions<<inout>> a valid non-null com.rti.dds.infrastructure.ConditionSeq object. Note that RTI Connext will not allocate a new object if active_conditions is null; the method will return com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
timeout<<in>> a wait timeout
Exceptions
Oneof the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET or com.rti.dds.infrastructure.RETCODE_TIMEOUT.
void attach_condition ( Condition  cond)

Attaches a com.rti.dds.infrastructure.Condition to the com.rti.dds.infrastructure.WaitSet.

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

Parameters
cond<<in>> Condition to be attached.
Exceptions
Oneof the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES.
void get_conditions ( ConditionSeq  attached_conditions)

Retrieves the list of attached com.rti.dds.infrastructure.Condition (s).

Parameters
attached_conditions<<inout>> a com.rti.dds.infrastructure.ConditionSeq object where the list of attached conditions will be returned
Exceptions
Oneof the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
void set_property ( WaitSetProperty_t  prop)

<<eXtension>> Sets the com.rti.dds.infrastructure.WaitSetProperty_t, to configure the associated com.rti.dds.infrastructure.WaitSet to return after one or more trigger events have occurred.

Parameters
prop<<in>>
Exceptions
Oneof the Standard Return Codes
void get_property ( WaitSetProperty_t  prop)

<<eXtension>> Retrieves the com.rti.dds.infrastructure.WaitSetProperty_t configuration of the associated com.rti.dds.infrastructure.WaitSet.

Parameters
prop<<out>>
Exceptions
Oneof the Standard Return Codes
void delete ( )

Destructor.

Releases the resources asociated with this com.rti.dds.infrastructure.WaitSet.

Calling this method multiple times on the same com.rti.dds.infrastructure.WaitSet is safe; subsequent deletions will have no effect.


RTI Connext Java API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc