<<extension>> A specialization of DDS_WaitSet that provides a mechanism to perform the wait asynchronously and uses a thread pool to dispatch the attached active DDS_Condition. More...
Data Structures | |
| struct | DDS_AsyncWaitSetProperty_t |
| Specifies the DDS_AsyncWaitSet behavior. More... | |
| struct | DDS_AsyncWaitSetListener |
| <<interface>> Listener for receiving event notifications related to the thread pool of the DDS_AsyncWaitSet. More... | |
Macros | |
| #define | DDS_AsyncWaitSetListener_INITIALIZER |
| Initializer for new DDS_AsyncWaitSetListener. More... | |
Typedefs | |
| typedef struct DDS_AsyncWaitSetImpl | DDS_AsyncWaitSet |
| A class for dispatching DDS_Condition objects using separate threads of execution. You can see this class as an extension of a DDS_WaitSet that allows asynchronously waiting for the attached DDS_Condition objects to trigger and provide a notification by calling DDS_Condition_dispatch. More... | |
| typedef struct DDS_AsyncWaitSetCompletionTokenImpl | DDS_AsyncWaitSetCompletionToken |
| <<interface>> Implementation of the completion token role element of the asynchronous completion token pattern that is part of the DDS_AsyncWaitSet behavior. More... | |
| typedef void(* | DDS_AsyncWaitSetListener_OnThreadSpawnedCallback) (void *listener_data, DDS_UnsignedLongLong thread_id) |
| Prototype of a DDS_AsyncWaitSetListener::on_thread_spawned function. More... | |
| typedef void(* | DDS_AsyncWaitSetListener_OnThreadDeletedCallback) (void *listener_data, DDS_UnsignedLongLong thread_id) |
| Prototype of a DDS_AsyncWaitSetListener::on_thread_deleted function. More... | |
| typedef void(* | DDS_AsyncWaitSetListener_OnWaitTimeoutCallback) (void *listener_data, DDS_UnsignedLongLong thread_id) |
| Prototype of a DDS_AsyncWaitSetListener::on_wait_timeout function. More... | |
| typedef struct DDS_DataReaderStatusConditionHandlerImpl | DDS_DataReaderStatusConditionHandler |
| <<interface>> Realization of a DDS_ConditionHandler that handles the status of a DDS_DataReader. More... | |
Variables | |
| DDS_AsyncWaitSetCompletionToken *const | DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT |
| For the operations that allow an DDS_AsyncWaitSetCompletionToken, this sentinel can be provided to indicate an DDS_AsyncWaitSet to use the implicit completion token and wait on it for request completion. More... | |
| DDS_AsyncWaitSetCompletionToken *const | DDS_ASYNC_WAITSET_COMPLETION_TOKEN_IGNORE |
| For the operations that allow an DDS_AsyncWaitSetCompletionToken, this sentinel can be provided to indicate an DDS_AsyncWaitSet to perform the action associating a 'null' completion token. More... | |
| const struct DDS_AsyncWaitSetProperty_t | DDS_ASYNC_WAITSET_PROPERTY_DEFAULT |
| Constant that defines the default property for a DDS_AsyncWaitSet. More... | |
Detailed Description
<<extension>> A specialization of DDS_WaitSet that provides a mechanism to perform the wait asynchronously and uses a thread pool to dispatch the attached active DDS_Condition.
This class is a realization of the Proactor pattern applied to WaitSets and Conditions that provide a powerful component for your application process events leveraging concurrency.
Macro Definition Documentation
◆ DDS_AsyncWaitSetListener_INITIALIZER
| #define DDS_AsyncWaitSetListener_INITIALIZER |
Initializer for new DDS_AsyncWaitSetListener.
No memory is allocated. New DDS_AsyncWaitSetListener Instances stored in the stack should be initialized with this value before they are passed to any functions.
Typedef Documentation
◆ DDS_AsyncWaitSet
| typedef struct DDS_AsyncWaitSetImpl DDS_AsyncWaitSet |
A class for dispatching DDS_Condition objects using separate threads of execution. You can see this class as an extension of a DDS_WaitSet that allows asynchronously waiting for the attached DDS_Condition objects to trigger and provide a notification by calling DDS_Condition_dispatch.
DDS_AsyncWaitSet provides a proactive model to process application events through DDS_Condition objects. DDS_AsyncWaitSet owns a pool of threads to asynchronously wait for the attached DDS_Condition objects to trigger and dispatch them upon wakeup. The asynchronous behavior is the main key different with regards to the DDS_WaitSet.
The class diagram and its collaborators is shown below:
AsyncWaitSet Thread Orchestration
DDS_AsyncWaitSet internally applies a leader-follower pattern for the orchestration of the thread pool. Once a DDS_AsyncWaitSet starts, it will create the thread pool of M threads from which only one thread will become the Leader thread, and remaining threads will become the Followers, where:
-
The
Leaderthread is the one waiting for the attached DDS_Condition to trigger. Remaining threads in the pool, if any, are either idle awaiting to become the leader or busy while processing active DDS_Condition. -
Upon wait wakeup, the
Leaderthread resigns its leader status to become aProcessorthread and dispatch the next active DDS_Condition through the DDS_Condition_dispatch operation. -
One of the
Followerthreads wakes up and becomes the new leader to resume the wait for DDS_Condition.
"Thread orchestration in a ::DDS_AsyncWaitSet"
This behavior implies the following considerations:
-
Only one thread a time can wait for the attached DDS_Condition objects to trigger. From a pool of
Mthreads, only one is the leader,Pare processing active DDS_Condition, andFare idle followers. - A thread can dispatch only one active DDS_Condition at a time.
- DDS_AsyncWaitSet efficiently distributes threads to dispatch DDS_Condition objects on demand. This avoids underutilizing a thread if DDS_Condition objects do not trigger or trigger unfrequently.
- At a given time, all the threads in the pool could be in processing state. In this situation, the DDS_AsyncWaitSet is not able to wait for more DDS_Condition objects until one thread becomes the leader.
DDS_AsyncWaitSet has a built-in dispatcher that guarantees fairness and avoids starvation of DDS_Condition objects. By applying a round-robin distribution policy, each attached and active DDS_Condition is dispatched within a finite period of time, assuming the DDS_ConditionHandler always return control after the DDS_Condition_dispatch operation.
AsyncWaitSet Thread Safety
A key aspect of the DDS_AsyncWaitSet is the thread safety. DDS_AsyncWaitSet interface is thread safe, so you can concurrently call any operation on the DDS_AsyncWaitSet object from multiple threads in your application.
Furthermore, DDS_AsyncWaitSet also safely interacts with its own thread pool. Internally, the DDS_AsyncWaitSet applies the asynchronous completion token pattern to perform activities that involve synchronization with the thread pool.
For instance to detach a DDS_Condition, the DDS_AsyncWaitSet generates an internal request to its thread pool to process it. As soon as the detachment completes, the thread pool provides the notification through an associated completion token.
- Note
- The asynchronous completion token behavior only takes place if the DDS_AsyncWaitSet is started. Otherwise the internal request will be directly executed by the calling thread.
For a finer control on this behavior, each DDS_AsyncWaitSet operation where this applies comes in two flavors:
-
Default:the operation hides all the details of the completion token and returns after the operation completes. Operations of this kind internally use an implicit DDS_AsyncWaitSetCompletionToken. The DDS_AsyncWaitSet creates and reuses DDS_AsyncWaitSetCompletionToken objects as needed. This is the recommended flavor unless your application has special resource needs. -
Withcompletiontoken:An overloaded version of the default one that also receives an DDS_AsyncWaitSetCompletionToken object on which you can wait on at any time for the actual operation to complete. This flavor is available to assist applications with resource constraints and that want more control on the interaction with the thread pool of the DDS_AsyncWaitSet.
Condition Locking
DDS_AsyncWaitSet incorporates a safety mechanism that prevents calling DDS_Condition_dispatch concurrently. DDS_AsyncWaitSet locks the DDS_Condition while a processor thread is dispatching it so no other thread within the pool can dispatch it again.
This mechanism ensures not only unexpected concurrent dispatch of a DDS_Condition but also spurious thread activity. Because it is responsibility of your application to reset the Condition trigger, there is a period of time in which the dispatched condition may remain active, causing the DDS_AsyncWaitSet to enter in a continous immediate wakeup from the wait. This behavior typically leads to thread hogging and high CPU usage.
Nevertheless, your application may still want to receive concurrent and controlled dispatch notifications. DDS_AsyncWaitSet will still allows you to unlock a DDS_Condition so any other available thread can dispatch the same condition concurrently while preventing the above mentioned problems. You can achive this by calling DDS_AsyncWaitSet_unlock_condition on the Condition being dispatched within the dispatch callback. Note that the AsyncWaitSet locks a Condition each time it dispatches it. Hence you need to unlock the Condition each time you want to enable a concurrent dispatch.
AsyncWaitSet Events and Resources
Besides DDS_Condition processing, you can listen to other kind of internal events related to the DDS_AsyncWaitSet and its thread pool by means of the DDS_AsyncWaitSetListener.
DDS_AsyncWaitSet exposes operations to start and stop the asynchronous wait, which involves the creation and deletion of the thread pool respectively.
DDS_AsyncWaitSet relies on thread-specific storage to provide the described functionality. Each application thread that calls an operation on a DDS_AsyncWaitSet will generate resources that will be associated with such thread. You can free these resources upon thread termination by calling DDS_DomainParticipantFactory_unregister_thread.
- MT Safety:
- Safe.
◆ DDS_AsyncWaitSetCompletionToken
| typedef struct DDS_AsyncWaitSetCompletionTokenImpl DDS_AsyncWaitSetCompletionToken |
<<interface>> Implementation of the completion token role element of the asynchronous completion token pattern that is part of the DDS_AsyncWaitSet behavior.
A DDS_AsyncWaitSetCompletionToken can be in one of the following states:
-
READY:The completion token can be used to associate a new request. Calling DDS_AsyncWaitSetCompletionToken_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 DDS_AsyncWaitSetCompletionToken_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 DDS_AsyncWaitSetCompletionToken_wait yet. Calling DDS_AsyncWaitSetCompletionToken_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 DDS_AsyncWaitSetCompletionToken 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 DDS_AsyncWaitSet operation that associates the completion token will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The completion token functionality can be viewed as a DDS_AsyncWaitSet internal detail from which your application should not need to know. In general, it is recommended to use the default flavor of DDS_AsyncWaitSet 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 DDS_AsyncWaitSet.
- MT Safety:
- Safe.
- See also
- DDS_AsyncWaitSet
◆ DDS_AsyncWaitSetListener_OnThreadSpawnedCallback
| typedef void(* DDS_AsyncWaitSetListener_OnThreadSpawnedCallback) (void *listener_data, DDS_UnsignedLongLong thread_id) |
Prototype of a DDS_AsyncWaitSetListener::on_thread_spawned function.
Each thread that conforms the thread pool of the DDS_AsyncWaitSet will invoke this operation sequentially as soon as the thread is spawned and right before it becomes the leader or a follower thread.
This callback is invoked by each thread conforming the pool and from its own context, right after it is spawned and the underlying operating system has allocated the necessary resources.
◆ DDS_AsyncWaitSetListener_OnThreadDeletedCallback
| typedef void(* DDS_AsyncWaitSetListener_OnThreadDeletedCallback) (void *listener_data, DDS_UnsignedLongLong thread_id) |
Prototype of a DDS_AsyncWaitSetListener::on_thread_deleted function.
Each thread that conforms the thread pool of the DDS_AsyncWaitSet will invoke this operation sequentially right before the thread finalizes its execution due to a stop request or an internal error.
This callback is invoked by each thread conforming the pool and from its own context, right before the underlying operating system releases the associarted resources.
◆ DDS_AsyncWaitSetListener_OnWaitTimeoutCallback
| typedef void(* DDS_AsyncWaitSetListener_OnWaitTimeoutCallback) (void *listener_data, DDS_UnsignedLongLong thread_id) |
Prototype of a DDS_AsyncWaitSetListener::on_wait_timeout function.
The leader thread of the DDS_AsyncWaitSet invokes this callback each time the wait operation timed out while waiting for the attached DDS_Condition objects to trigger.
- Parameters
-
listener_data <<in>> Data associated with the listener when the listener is set. thread_id <<in>> Thread ID of the current context. It always corresponds to the current leader thread.
- See also
- DDS_WaitSet_wait
◆ DDS_DataReaderStatusConditionHandler
| typedef struct DDS_DataReaderStatusConditionHandlerImpl DDS_DataReaderStatusConditionHandler |
<<interface>> Realization of a DDS_ConditionHandler that handles the status of a DDS_DataReader.
A DDS_DataReaderStatusConditionHandler demultiplexes a DDS_DataReader status change into the corresponding callback of a provided DDS_DataReaderListener implementation.
Note that the DDS_DataReaderListener notifications have different considerations than if the were made by the DDS_DataReader directly:
- Context: The DDS_DataReaderListener callback context is the one of the thread that dispatches the DDS_Condition where this handler is set. For instance, if you attach the condition to a DDS_AsyncWaitSet, the context will be one of the threads within the pool.
- Status clearing: All the DDS_DataReader's enabled statuses are cleared upon condition dispatch except the DDS_DATA_AVAILABLE_STATUS, which will not be cleared until your application reads the data.
- Exclusive Area: Restrictions depend on the context of the dipsatching thread. For instance, if the DDS_AsyncWaitSet dispatches the condition, the listener notications are free of any exclusive area restrictions.
The DDS_DataReaderStatusConditionHandler is a convenience to handle the status changes of a DDS_DataReader. You can install a DDS_DataReaderStatusConditionHandler as the handler of a reader's DDS_StatusCondition. You can then attach it to a DDS_WaitSet or DDS_AsyncWaitSet and receive status changes notifications through a specific DDS_DataReaderListener implementation instance.
Function Documentation
◆ DDS_AsyncWaitSetCompletionToken_wait()
| DDS_ReturnCode_t DDS_AsyncWaitSetCompletionToken_wait | ( | DDS_AsyncWaitSetCompletionToken * | self, |
| const struct DDS_Duration_t * | max_wait | ||
| ) |
Waits for the request associated to an operation made on the DDS_AsyncWaitSet to complete.
This operation will block the calling thread for a maximum amount of time specified by max_wait until the DDS_AsyncWaitSet 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 DDS_AsyncWaitSet, 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
-
self <<in>> Cannot be NULL. 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
- DDS_AsyncWaitSet
◆ DDS_AsyncWaitSet_get_property()
| DDS_ReturnCode_t DDS_AsyncWaitSet_get_property | ( | DDS_AsyncWaitSet * | self, |
| struct DDS_AsyncWaitSetProperty_t * | property | ||
| ) |
Retrieves the DDS_AsyncWaitSetProperty_t configuration of the associated DDS_AsyncWaitSet.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_detach_condition()
| DDS_ReturnCode_t DDS_AsyncWaitSet_detach_condition | ( | DDS_AsyncWaitSet * | self, |
| DDS_Condition * | condition | ||
| ) |
Deaches the specified DDS_Condition from this DDS_AsyncWaitSet.
This operation is equivalent to call DDS_AsyncWaitSet_detach_condition_with_completion_token providing DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT as a completion_token.
This operation blocks until the detach request completes. Upon successful return, it is guaranteed that the specified DDS_Condition is detached.
- Parameters
-
self <<in>> Cannot be NULL. condition <<in>> DDS_Condition to be detached.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_detach_condition_with_completion_token()
| DDS_ReturnCode_t DDS_AsyncWaitSet_detach_condition_with_completion_token | ( | DDS_AsyncWaitSet * | self, |
| DDS_Condition * | condition, | ||
| DDS_AsyncWaitSetCompletionToken * | completion_token | ||
| ) |
Detaches the specified DDS_Condition from this DDS_AsyncWaitSet.
If this operation succeeds, a detach request has been scheduled and your application can use the provided completion_token to wait for this DDS_AsyncWaitSet to process the request. If the DDS_AsyncWaitSetCompletionToken_wait operation returns successfully, it is guaranteed that the DDS_Condition is detached from this DDS_AsyncWaitSet.
Once the DDS_Condition is detached, it is guaranteed that the DDS_AsyncWaitSet will no longer process it so it is safe for your application to release any resources associated with the detached DDS_Condition.
DDS_Condition may be detached at any time independently of the state of the DDS_AsyncWaitSet.
- Parameters
-
self <<in>> Cannot be NULL. condition <<in>> DDS_Condition to be detached. completion_token <<inout>> a valid DDS_AsyncWaitSetCompletionToken instance that can be used by your application to wait for the detach request to complete. You can provide one of the special sentinels DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT and DDS_ASYNC_WAITSET_COMPLETION_TOKEN_IGNORE.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_attach_condition()
| DDS_ReturnCode_t DDS_AsyncWaitSet_attach_condition | ( | DDS_AsyncWaitSet * | self, |
| DDS_Condition * | condition | ||
| ) |
Attaches the specified DDS_Condition to this DDS_AsyncWaitSet.
This operation is equivalent to calling DDS_AsyncWaitSet_attach_condition_with_completion_token providing DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT as a completion_token.
This operation will block until the attach request completes. Upon successful return, it is guaranteed that the specified DDS_Condition is attached.
- Parameters
-
self <<in>> Cannot be NULL. condition <<in>> DDS_Condition to be attached.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_attach_condition_with_completion_token()
| DDS_ReturnCode_t DDS_AsyncWaitSet_attach_condition_with_completion_token | ( | DDS_AsyncWaitSet * | self, |
| DDS_Condition * | condition, | ||
| DDS_AsyncWaitSetCompletionToken * | completion_token | ||
| ) |
Attaches the specified DDS_Condition to this DDS_AsyncWaitSet.
If this operation succeeds, an attach request has been scheduled and your application can use the output parameter completion_token to wait for this DDS_AsyncWaitSet to process the request. DDS_AsyncWaitSetCompletionToken_wait operation returns successfully, it is guaranteed that the DDS_Condition is attached to this DDS_AsyncWaitSet.
Once the DDS_Condition is attached, its trigger value may cause the leader thread of the DDS_AsyncWaitSet to wake up call the DDS_Condition_dispatch operation.
DDS_Condition may be attached at any time independently of the state of the DDS_AsyncWaitSet.
- Parameters
-
self <<in>> Cannot be NULL. condition <<in>> DDS_Condition to be attached. completion_token <<inout>> a valid DDS_AsyncWaitSetCompletionToken instance that can be used by your application to wait for the attach request to complete. You can provide one of the special sentinels DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT and DDS_ASYNC_WAITSET_COMPLETION_TOKEN_IGNORE.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_unlock_condition()
| DDS_ReturnCode_t DDS_AsyncWaitSet_unlock_condition | ( | DDS_AsyncWaitSet * | self, |
| DDS_Condition * | condition | ||
| ) |
Allows the DDS_Condition under dispatch to be available for concurrent dispatch from another thread from the pool.
This operation can be called from the dispatch callback of the DDS_Condition this DDS_AsyncWaitSet is dispatching. After succesfully calling this operation, if the DDS_Condition becomes active this DDS_AsyncWaitSet is allowed to dispatch it again from any available thread from the pool.
You may call this operation any time you need the same DDS_Condition to be dispatched concurrently.
This operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if you call it from a different context than the dispatch callback or on a different DDS_Condition.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_get_conditions()
| DDS_ReturnCode_t DDS_AsyncWaitSet_get_conditions | ( | DDS_AsyncWaitSet * | self, |
| struct DDS_ConditionSeq * | attached_conditions | ||
| ) |
Retrieves the list of attached DDS_Condition (s).
- Parameters
-
self <<in>> Cannot be NULL. attached_conditions <<inout>> a DDS_ConditionSeq object where the list of attached conditions will be returned.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_stop()
| DDS_ReturnCode_t DDS_AsyncWaitSet_stop | ( | DDS_AsyncWaitSet * | self | ) |
Initiates the stop procedure on this DDS_AsyncWaitSet that will stop the asynchronous wait.
This operation is equivalent to calling DDS_AsyncWaitSet_stop_with_completion_token providing DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT as a completion_token.
This operation will block until the stop request completes. Upon successful return, it is guaranteed that this DDS_AsyncWaitSet stopped the asynchronous wait and dispatch.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_stop_with_completion_token()
| DDS_ReturnCode_t DDS_AsyncWaitSet_stop_with_completion_token | ( | DDS_AsyncWaitSet * | self, |
| DDS_AsyncWaitSetCompletionToken * | completion_token | ||
| ) |
Initiates the stop procedure on this DDS_AsyncWaitSet that will stop the asynchronous wait.
If this operation succeeds, a stop request has been scheduled and your application can use the provided completion_token to wait for this DDS_AsyncWaitSet to process the request. If the DDS_AsyncWaitSetCompletionToken_wait operation returns successfully, it is guranteed that the thread pool has been deleted and this DDS_AsyncWaitSet no longer process any of the attached DDS_Condition objects.
Once this DDS_AsyncWaitSet is stopped, the DDS_Condition_dispatch will no longer be called on any of the attached DDS_Condition, no matter what their trigger value is.
The stop procedure causes the DDS_AsyncWaitSet to delete all the threads within the thread pool, which involves the underlying operating system to release the associated thread stack and context of each thread. If a DDS_AsyncWaitSetListener is installed, this DDS_AsyncWaitSet will sequentially invoke the DDS_AsyncWaitSetListener::on_thread_deleted once per deleted thread.
If this DDS_AsyncWaitSet is already stopped, this operation will return immediately with success, and waiting on the completion_token will also return immediately with success.
- Parameters
-
self <<in>> Cannot be NULL. completion_token <<inout>> a valid DDS_AsyncWaitSetCompletionToken instance that can be used by your application to wait for the stop request to complete. You can provide one of the special sentinels DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT and DDS_ASYNC_WAITSET_COMPLETION_TOKEN_IGNORE.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_start()
| DDS_ReturnCode_t DDS_AsyncWaitSet_start | ( | DDS_AsyncWaitSet * | self | ) |
Initiates the asynchronous wait on this DDS_AsyncWaitSet.
This operation is equivalent to calling DDS_AsyncWaitSet_start_with_completion_token providing DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT as a completion_token.
This operation blocks until the start request completes. Upon successful return, it is guaranteed that this DDS_AsyncWaitSet has initiated the asynchronous wait and dispatch.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_start_with_completion_token()
| DDS_ReturnCode_t DDS_AsyncWaitSet_start_with_completion_token | ( | DDS_AsyncWaitSet * | self, |
| DDS_AsyncWaitSetCompletionToken * | completion_token | ||
| ) |
Initiates the asynchronous wait on this DDS_AsyncWaitSet.
If this operation succeeds, a start request has been scheduled and your application can use the provided completion_token to wait for this DDS_AsyncWaitSet to process the request. If the DDS_AsyncWaitSetCompletionToken_wait operation returns successfully, it is guranteed that the thread pool has been created and the leader thread is waiting for the attached DDS_Condition to trigger.
Once this DDS_AsyncWaitSet is started, attached DDS_Condition will be dispatched through the DDS_Condition_dispatch operation when they trigger.
The start procedure causes the DDS_AsyncWaitSet to spawn all the threads within the thread pool, which involves the underlying operating system to allocate the associated thread stack and context for each thread. If a DDS_AsyncWaitSetListener is installed, this DDS_AsyncWaitSet will sequentially invoke the DDS_AsyncWaitSetListener::on_thread_spawned once per spwaned thread.
A DDS_AsyncWaitSet can be restarted after a stop. If this DDS_AsyncWaitSet is already started, this operation will return immediately with success, and waiting on the completion_token will also return immediately with success.
- Parameters
-
self <<in>> Cannot be NULL. completion_token <<inout>> a valid DDS_AsyncWaitSetCompletionToken instance that can be used by your application to wait for the start request to complete. You can provide one of the special sentinels DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT and DDS_ASYNC_WAITSET_COMPLETION_TOKEN_IGNORE.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_is_started()
| DDS_Boolean DDS_AsyncWaitSet_is_started | ( | DDS_AsyncWaitSet * | self | ) |
Returns whether this DDS_AsyncWaitSet is started.
A DDS_AsyncWaitSet is started if all the threads within the thread pool have been created and are running.
- Parameters
-
self <<in>> Cannot be NULL.
- Returns
- DDS_BOOLEAN_TRUE if started.
◆ DDS_AsyncWaitSet_create_completion_token()
| DDS_AsyncWaitSetCompletionToken * DDS_AsyncWaitSet_create_completion_token | ( | DDS_AsyncWaitSet * | self | ) |
Creates a new DDS_AsyncWaitSetCompletionToken.
All the created DDS_AsyncWaitSetCompletionToken must be deleted by calling DDS_AsyncWaitSet_delete_completion_token.
- Returns
- A new DDS_AsyncWaitSetCompletionToken or NULL on error.
◆ DDS_AsyncWaitSet_delete_completion_token()
| DDS_ReturnCode_t DDS_AsyncWaitSet_delete_completion_token | ( | DDS_AsyncWaitSet * | self, |
| DDS_AsyncWaitSetCompletionToken * | completion_token | ||
| ) |
Deletes a DDS_AsyncWaitSetCompletionToken previously created from this DDS_AsyncWaitSet.
This operation will fail the if the specified completion_token was not created from this DDS_AsyncWaitSet.
This operation will fail if the specified completion_token is associated with a request that has not completed yet.
- Parameters
-
self <<in>> Cannot be NULL. completion_token <<inout>> a valid DDS_AsyncWaitSetCompletionToken created from this DDS_AsyncWaitSet.
- Returns
- One of the Standard Return Codes
◆ DDS_AsyncWaitSet_new()
| DDS_AsyncWaitSet * DDS_AsyncWaitSet_new | ( | const struct DDS_AsyncWaitSetProperty_t * | property | ) |
Single-argument constructor that allows creating a a DDS_AsyncWaitSet with custom behavior.
You can provide DDS_ASYNC_WAITSET_PROPERTY_DEFAULT as property to create an DDS_AsyncWaitSet with default behavior.
The DDS_AsyncWaitSet is created with no listener installed.
- Parameters
-
property <<in>> configuration DDS_AsyncWaitSetProperty_t
- Returns
- A new DDS_AsyncWaitSet or NULL if one could not be allocated.
◆ DDS_AsyncWaitSet_new_with_listener()
| DDS_AsyncWaitSet * DDS_AsyncWaitSet_new_with_listener | ( | const struct DDS_AsyncWaitSetProperty_t * | property, |
| struct DDS_AsyncWaitSetListener * | listener | ||
| ) |
Constructor that allows specifying a DDS_AsyncWaitSetListener.
Creates a new DDS_AsyncWaitSet with the specified property DDS_AsyncWaitSetProperty_t and DDS_AsyncWaitSetListener.
- Parameters
-
property <<in>> configuration DDS_AsyncWaitSetProperty_t listener <<in>> the DDS_AsyncWaitSetListener. Cannot be NULL.
- Returns
- A new DDS_AsyncWaitSet or NULL if one could not be allocated.
◆ DDS_AsyncWaitSet_new_with_thread_factory()
| DDS_AsyncWaitSet * DDS_AsyncWaitSet_new_with_thread_factory | ( | const struct DDS_AsyncWaitSetProperty_t * | property, |
| struct DDS_AsyncWaitSetListener * | listener, | ||
| struct DDS_ThreadFactory * | thread_factory | ||
| ) |
Constructor with arguments that allow specifying behavior different than the default one, including specifying a DDS_ThreadFactory for the creation and deletion of the threads within the thread pool.
This operation extends DDS_AsyncWaitSet_new_with_listener by allowing to provide a DDS_ThreadFactory
- Parameters
-
property <<in>> configuration DDS_AsyncWaitSetProperty_t listener <<in>> the DDS_AsyncWaitSetListener. Cannot be NULL. thread_factory <<in>> DDS_ThreadFactory for the creation and deletion of threads.
- Returns
- A new DDS_AsyncWaitSet or NULL if one could not be allocated.
◆ DDS_AsyncWaitSet_delete()
| DDS_ReturnCode_t DDS_AsyncWaitSet_delete | ( | DDS_AsyncWaitSet * | self | ) |
Deletes a DDS_AsyncWaitSet.
If the DDS_AsyncWaitSet is started, this operation will initiate the stop procedure and block until it completes.
The deletion will fail if there are outstanding DDS_AsyncWaitSetCompletionToken that have not been deleted.
Any outstanding DDS_AsyncWaitSet must be deleted before finalizing the DDS_DomainParticipantFactory. Otherwise undefined behavior may occur.
- Parameters
-
self <<in>> Cannot be NULL.
- See also
- DDS_AsyncWaitSet_new
◆ DDS_DataReaderStatusConditionHandler_new()
| DDS_DataReaderStatusConditionHandler * DDS_DataReaderStatusConditionHandler_new | ( | DDS_DataReader * | reader, |
| const struct DDS_DataReaderListener * | listener, | ||
| DDS_StatusMask | listener_mask | ||
| ) |
Creates a new DDS_DataReaderStatusConditionHandler instance.
The created DataReaderStatusConditionHandler can set as DDS_ConditionHandler in any DDS_Condition and will demultiplex the specified status changes from the specified DDS_DataReader
- Parameters
-
reader <<in>> The DDS_DataReader for which the status changes are demultiplexed to the specified listenerlistener <<in>> that receives the status changes notifications from the specified reader.listener_mask <<in>> Specifies which status changes from thereader to demultiplex to thelistener.
- Returns
- A new instance or NULL on error.
◆ DDS_DataReaderStatusConditionHandler_delete()
| DDS_ReturnCode_t DDS_DataReaderStatusConditionHandler_delete | ( | DDS_DataReaderStatusConditionHandler * | self | ) |
Deletes a DDS_DataReaderStatusConditionHandler instance previously created with DDS_DataReaderStatusConditionHandler_new.
- Returns
- One of the Standard Return Codes
Variable Documentation
◆ DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT
| DDS_AsyncWaitSetCompletionToken* const DDS_ASYNC_WAITSET_COMPLETION_TOKEN_USE_IMPLICIT_AND_WAIT |
For the operations that allow an DDS_AsyncWaitSetCompletionToken, this sentinel can be provided to indicate an DDS_AsyncWaitSet to use the implicit completion token and wait on it for request completion.
If this sentinel is used, the DDS_AsyncWaitSet will use the completion token associated with the calling thread and will wait with an infinite timeout until the request completes successfully.
◆ DDS_ASYNC_WAITSET_COMPLETION_TOKEN_IGNORE
| DDS_AsyncWaitSetCompletionToken* const DDS_ASYNC_WAITSET_COMPLETION_TOKEN_IGNORE |
For the operations that allow an DDS_AsyncWaitSetCompletionToken, this sentinel can be provided to indicate an DDS_AsyncWaitSet to perform the action associating a 'null' completion token.
This sentinel is a realization of the null object pattern of an DDS_AsyncWaitSetCompletionToken. If this object is provided to a DDS_AsyncWaitSet operation, the resulting operation request will be associated with a 'null' completion token that behaves as no-op.
When 'nul' completion token is provided, the DDS_AsyncWaitSet operation returns immediately after it issues the internal request, and there is no mean for your application to wait for the request to complete.
You can use this sentinel when your application can operate on an DDS_AsyncWaitSet without needing to known when operation requests complete or your application uses other strategies to synchronize resources.
This sentinel is also useful when you need to perform operations on DDS_AsyncWaitSet from within one of the threads from its thread pool, where waiting on a valid DDS_AsyncWaitSetCompletionToken is forbidden.
◆ DDS_ASYNC_WAITSET_PROPERTY_DEFAULT
| const struct DDS_AsyncWaitSetProperty_t DDS_ASYNC_WAITSET_PROPERTY_DEFAULT |
Constant that defines the default property for a DDS_AsyncWaitSet.
Value: wait_set_property = DDS_WaitSetProperty_t_INITIALIZER, thread_pool_size = 1, thread_settings DDS_THREAD_SETTINGS_DEFAULT, thread_base_name = NULL wait_timeout = DDS_DURATION_INFINITE level = 1