RTI Connext Traditional C++ API  Version 6.1.0
DDSAsyncWaitSetCompletionToken Class Referenceabstract

<<interface>> Implementation of the completion token role element of the asynchronous completion token pattern that is part of the DDSAsyncWaitSet behavior. More...

Public Member Functions

virtual DDS_ReturnCode_t wait (const DDS_Duration_t &max_wait)=0
 Waits for the request associated to an operation made on the DDSAsyncWaitSet to complete. More...
 

Detailed Description

<<interface>> Implementation of the completion token role element of the asynchronous completion token pattern that is part of the DDSAsyncWaitSet behavior.

A DDSAsyncWaitSetCompletionToken can be in one of the following states:

  • READY: The completion token can be used to associate a new request. Calling DDSAsyncWaitSetCompletionToken::wait on a ready completion token will return immediately with success. A ready completion token can only transition to the queued state.
  • QUEUED: The completion token has an associated request that is pending processing. Calling DDSAsyncWaitSetCompletionToken::wait on a queued completion token will block until the request completes or times out. A queued completion token can only transition to the processed state.
  • PROCESS: The completion token has an associated request that has been processed but the application did not call DDSAsyncWaitSetCompletionToken::wait yet. Calling DDSAsyncWaitSetCompletionToken::wait on a processed completion token will return immediately with the return code result of processing the associated request. A processed completion token can transition to both ready or queued states.

AsyncWaitSetCompletionToken management

The same DDSAsyncWaitSetCompletionToken instance can be reused reused multiple times to associate a request and wait for its completion. Reusing is allowed only if the completion token is either in READY or PROCESSED state. Otherwise the DDSAsyncWaitSet operation that associates the completion token will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

The completion token functionality can be viewed as a DDSAsyncWaitSet internal detail from which your application should not need to know. In general, it is recommended to use the default flavor of DDSAsyncWaitSet operations that handle the internals of the completion tokens for you.

Nevertheless, if a completion token represents an expensive resource in your environment, your application may want to have full control of how and when completion tokens are created. It's for these reasons why is exposed as a public collaborator of the DDSAsyncWaitSet.

MT Safety:
Safe.
See also
DDSAsyncWaitSet

Member Function Documentation

◆ wait()

virtual DDS_ReturnCode_t DDSAsyncWaitSetCompletionToken::wait ( const DDS_Duration_t max_wait)
pure virtual

Waits for the request associated to an operation made on the DDSAsyncWaitSet to complete.

This operation will block the calling thread for a maximum amount of time specified by max_wait until the DDSAsyncWaitSet request associated with this completion token completes.

If there is no timeout, upon return it is guaranteed that the request associated with this token completed. This operation may fail due to an error during the wait or while processing the associated request.

If this operation is called from within the context of one the thread that conforms the thread poolof the DDSAsyncWaitSet, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

If the operation failed with DDS_RETCODE_TIMEOUT your application can wait again on this completion token.

Parameters
max_wait<<in>> Cannot be NULL. Maximum time to wait for the request associated to this completion token to complete before timeout.
Returns
One of the Standard Return Codes
See also
DDSAsyncWaitSet