dds::core::cond::WaitSet Class Reference

A WaitSet object allows an application to wait until one or more of the attached Condition objects has a trigger_value of TRUE or else until the timeout expires. More...

#include "WaitSet.hpp"

Inherits dds::core::Reference< DELEGATE >.

Public Types
typedef std::vector< dds::core::cond::Condition >	ConditionSeq

Public Member Functions
	WaitSet ()
WaitSet &	attach_condition (const dds::core::cond::Condition &cond)
const ConditionSeq	conditions () const
ConditionSeq &	conditions (ConditionSeq &conds) const
bool	detach_condition (const dds::core::cond::Condition &cond)
void	dispatch ()
void	dispatch (const dds::core::Duration &timeout)
bool	is_nil () const
bool	operator!= (const null_type nil) const
template<typename R >
bool	operator!= (const R &ref) const
WaitSet &	operator+= (const dds::core::cond::Condition &cond)
WaitSet &	operator-= (const dds::core::cond::Condition &cond)
DELEGATE *	operator-> ()
const DELEGATE *	operator-> () const
bool	operator== (const null_type) const
template<typename R >
bool	operator== (const R &ref) const
const ConditionSeq	wait ()
ConditionSeq &	wait (ConditionSeq &triggered)
ConditionSeq &	wait (ConditionSeq &triggered, const dds::core::Duration &timeout)
const ConditionSeq	wait (const dds::core::Duration &timeout)

Detailed Description

A WaitSet object allows an application to wait until one or more of the attached Condition objects has a trigger_value of TRUE or else until the timeout expires.

A WaitSet is not necessarily associated with a single DomainParticipant and could be used to wait for Condition objects associated with different DomainParticipant objects.

Example with wait()
When using the wait() operation, the triggered Conditions are returned in a list.

// Create a Condition to attach to a Waitset
dds::core::cond::StatusCondition readerSC = dds::core::cond::StatusCondition(reader);
readerSC.enabled_statuses(dds::core::status::StatusMask::data_available());
 
// Create WaitSet and attach Condition
dds::core::cond::WaitSet waitset;
waitset.attach_condition(readerSC); // or waitset += readerSC;
 
dds::core::cond::WaitSet::ConditionSeq conditions;
while(true) {
    // Wait for any Condition to trigger.
    conditions = waitset.wait();
 
    // Loop through the triggered conditions.
    for (int i=0; i < conditions.size(); i++) {
        // Handle data_available when right Condition triggered.
        if (conditions[i] == readerSC) {
            // Read samples from the DataReader
        }
    }
}

Example with dispatch()
When using the dispatch() operation, the Functors of the triggered Conditions will be called.

// Functor to add to a Condition
class FunctorStatusCondition {
public:
    void operator()(const dds::core::cond::StatusCondition& condition) {
        // Possibly get reader from the condition and read some samples.
    }
};
FunctorStatusCondition functor;
 
// Create a Condition with functor to attach to a Waitset
dds::core::cond::StatusCondition readerSC = dds::core::cond::StatusCondition(reader, functor);
readerSC.enabled_statuses(dds::core::status::StatusMask::data_available());
 
// Create WaitSet and attach Condition
dds::core::cond::WaitSet waitset;
waitset.attach_condition(readerSC); // or waitset += readerSC;
 
while(true) {
    // Wait for any Condition to trigger.
    // The functors of the Conditions are automatically called
    // when the Condition triggers.
    waitset.dispatch();
}

See also

WaitSet concept

Definition at line 110 of file WaitSet.hpp.

Member Typedef Documentation

ConditionSeq

typedef std::vector<dds::core::cond::Condition> dds::core::cond::WaitSet::ConditionSeq

Definition at line 113 of file WaitSet.hpp.

Constructor & Destructor Documentation

WaitSet()

dds::core::cond::WaitSet::WaitSet

(

)

Create a WaitSet instance.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

Member Function Documentation

attach_condition()

WaitSet& dds::core::cond::WaitSet::attach_condition

(

const dds::core::cond::Condition &

cond

)

This operation attaches a Condition to the WaitSet.

Attaches a Condition to the WaitSet. It is possible to attach a Condition on a WaitSet that is currently being waited upon (via the wait operation). In this case, if the Condition has a trigger_value 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 be attached to this WaitSet.

Returns

WaitSet The WaitSet itself so that attaching Conditions can be chained.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

conditions() [1/2]

const ConditionSeq dds::core::cond::WaitSet::conditions

(

)

const

This operation retrieves the list of attached Conditions.

The resulting sequence will either be an empty sequence, meaning there were no conditions attached, or will contain a list of ReadCondition, QueryCondition, StatusCondition and GuardCondition.

Returns

ConditionSeq The list of attached Conditions.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

conditions() [2/2]

ConditionSeq& dds::core::cond::WaitSet::conditions

(

ConditionSeq &

conds

)

const

This operation retrieves the list of attached Conditions.

The resulting sequence will either be an empty sequence, meaning there were no conditions attached, or will contain a list of ReadCondition, QueryCondition, StatusCondition and GuardCondition.

Parameters

conds

A ConditionSeq in which to put the attached Conditions.

Returns

ConditionSeq The list of attached Conditions.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

detach_condition()

bool dds::core::cond::WaitSet::detach_condition

(

const dds::core::cond::Condition &

cond

)

This operation detaches a Condition to the WaitSet.

Detaches a Condition from the WaitSet. If the Condition was not attached to the WaitSet, the operation will return false.

Parameters

cond	The Condition to detach from this WaitSet

Returns

bool True if the Condition was found and detached, False if the Condition was not part of the WaitSet.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

dispatch() [1/2]

void dds::core::cond::WaitSet::dispatch

(

)

Waits for at least one of the attached Conditions to trigger and then dispatches the functor associated with the Condition.

Returns

void

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::PreconditionNotMetError	When multiple thread try to invoke the function concurrently.

dispatch() [2/2]

void dds::core::cond::WaitSet::dispatch

(

const dds::core::Duration &

timeout

)

Waits for at least one of the attached Conditions to trigger and then dispatches the functor associated with the Condition, or, times out and throws a TimeoutError.

Parameters

timeout

The maximum amount of time for which the dispatch should block while waiting for a Condition to be triggered.

Returns

void

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::TimeoutError	The timeout has elapsed without any of the attached conditions becoming TRUE.
dds::core::PreconditionNotMetError	When multiple thread try to invoke the function concurrently.

is_nil()

template<typename DELEGATE>

bool dds::core::Reference< DELEGATE >::is_nil ( ) const

inherited

Check if the referenced object is nil.

In other words, check if the reference is pointing to a null object.

Returns

true if the referenced object is null.

operator!=() [1/2]

template<typename DELEGATE>

bool dds::core::Reference< DELEGATE >::operator!= ( const null_type  nil ) const

inherited

Special operator!= used to check if this reference object does not equal the dds::core::null reference.

The non-null-check can be done like this:

if (r != dds::core::null) {
   // Use the dds reference object r
}

Returns

true if this reference is not null.

operator!=() [2/2]

template<typename DELEGATE>

template<typename R >

bool dds::core::Reference< DELEGATE >::operator!= ( const R &  ref ) const

inherited

Compares two Reference objects and returns true if they are not equal.

Inequality is based on the referential inequality of the object being pointed to.

Parameters

ref	the other Reference object

Returns

true when not equal

operator+=()

WaitSet& dds::core::cond::WaitSet::operator+=

(

const dds::core::cond::Condition &

cond

)

This operation attaches a Condition to the WaitSet.

Attaches a Condition to the WaitSet. It is possible to attach a Condition on a WaitSet that is currently being waited upon (via the wait operation). In this case, if the Condition has a trigger_value 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 be attached to this WaitSet.

Returns

WaitSet The WaitSet itself so that attaching Conditions can be chained.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

operator-=()

WaitSet& dds::core::cond::WaitSet::operator-=

(

const dds::core::cond::Condition &

cond

)

This operation detaches a Condition to the WaitSet.

Detaches a Condition from the WaitSet. If the Condition was not attached to the WaitSet, the operation will return false.

Parameters

cond	The Condition to detach from this WaitSet

Returns

bool True if the Condition was found and detached, False if the Condition was not part of the WaitSet.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

operator->() [1/2]

template<typename DELEGATE>

DELEGATE* dds::core::Reference< DELEGATE >::operator-> ( )

inherited

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();

Returns

a reference to delegate.

operator->() [2/2]

template<typename DELEGATE>

const DELEGATE* dds::core::Reference< DELEGATE >::operator-> ( ) const

inherited

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();

Returns

a reference to delegate.

operator==() [1/2]

template<typename DELEGATE>

bool dds::core::Reference< DELEGATE >::operator== ( const  null_type ) const

inherited

Special operator== used to check if this reference object equals the dds::core::null reference.

The null-check can be done like this:

if (r == dds::core::null) {
   // Do not use the dds reference object r in its current state
}

Returns

true if this reference is null.

operator==() [2/2]

template<typename DELEGATE>

template<typename R >

bool dds::core::Reference< DELEGATE >::operator== ( const R &  ref ) const

inherited

Compares two Reference objects and returns true if they are equal.

Equality is based on the referential equality of the object being pointed.

Parameters

ref	the other Reference object

Returns

true when equal

wait() [1/4]

const ConditionSeq dds::core::cond::WaitSet::wait

(

)

This operation allows an application thread to wait for the occurrence of at least one of the conditions that is attached to the WaitSet.

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 trigger_value of TRUE, the wait operation will block suspending the calling thread.

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the wait operation is invoked on a WaitSet that already has a thread blocking on it, the operation will immediately raise a PreconditionNotMetError exception.

The result of the wait operation is the list of all the attached Conditions that have a trigger_value of TRUE (i.e., the Conditions that unblocked the wait).

Returns

ConditionSeq A vector containing the triggered Conditions

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::PreconditionNotMetError	When multiple thread try to invoke the function concurrently.

wait() [2/4]

ConditionSeq& dds::core::cond::WaitSet::wait

(

ConditionSeq &

triggered

)

This operation allows an application thread to wait for the occurrence of at least one of the conditions that is attached to the WaitSet.

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 trigger_value of TRUE, the wait operation will block suspending the calling thread.

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the wait operation is invoked on a WaitSet that already has a thread blocking on it, the operation will immediately raise a PreconditionNotMetError exception.

The result of the wait operation is the list of all the attached Conditions that have a trigger_value of TRUE (i.e., the Conditions that unblocked the wait).

Parameters

triggered

A ConditionSeq in which to put Conditions that were triggered during the wait.

Returns

ConditionSeq A vector containing the triggered Conditions

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::PreconditionNotMetError	When multiple thread try to invoke the function concurrently.

wait() [3/4]

ConditionSeq& dds::core::cond::WaitSet::wait	(	ConditionSeq &	triggered,
		const dds::core::Duration &	timeout
	)

This operation allows an application thread to wait for the occurrence of at least one of the conditions that is attached to the WaitSet.

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 trigger_value of TRUE, the wait operation will block suspending the calling thread.

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 Condition objects is true, a TimeoutError will be thrown.

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the wait operation is invoked on a WaitSet that already has a thread blocking on it, the operation will immediately raise a PreconditionNotMetError exception.

The result of the wait operation is the list of all the attached Conditions that have a trigger_value of TRUE (i.e., the Conditions that unblocked the wait).

Parameters

triggered	A ConditionSeq in which to put Conditions that were triggered during the wait.
timeout	The maximum amount of time for which the wait should block while waiting for a Condition to be triggered.

Returns

ConditionSeq A vector containing the triggered Conditions

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::TimeoutError	The timeout has elapsed without any of the attached conditions becoming TRUE.
dds::core::PreconditionNotMetError	When multiple thread try to invoke the function concurrently.

wait() [4/4]

const ConditionSeq dds::core::cond::WaitSet::wait

(

const dds::core::Duration &

timeout

)

This operation allows an application thread to wait for the occurrence of at least one of the conditions that is attached to the WaitSet.

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 trigger_value of TRUE, the wait operation will block suspending the calling thread.

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 Condition objects is true, a TimeoutError will be thrown.

It is not allowed for more than one application thread to be waiting on the same WaitSet. If the wait operation is invoked on a WaitSet that already has a thread blocking on it, the operation will immediately raise a PreconditionNotMetError exception.

The result of the wait operation is the list of all the attached Conditions that have a trigger_value of TRUE (i.e., the Conditions that unblocked the wait).

Parameters

timeout

The maximum amount of time for which the wait should block while waiting for a Condition to be triggered.

Returns

ConditionSeq A vector containing the triggered Conditions

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The WaitSet was not properly created and references to dds::core::null.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::TimeoutError	The timeout has elapsed without any of the attached conditions becoming TRUE.
dds::core::PreconditionNotMetError	When multiple thread try to invoke the function concurrently.

---

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

• dds/core/cond/WaitSet.hpp