NXTimeOutCancel
Cancels a scheduled timeout.
Syntax
#include <nks/time.h>
int NXTimeOutCancel (
NXTimeOut_t *tout,
NXBool_t wait,
NXBool_t *status);
Parameters
- tout
-
(IN) Points to the timeout to cancel.
- wait
-
(IN) Specifies whether the caller is willing to wait (when the timeout might be active at the same time the attempt is made to cancel it):
- TRUE Wait
- FALSE Do not wait
- status
-
(OUT) Points to the status of the cancellation. Either:
- TRUE The timeout was successfully cancelled
- FALSE The timeout had already executed and could not be cancelled
Return Values
If successful, returns 0; otherwise, returns a nonzero error code:
Remarks
If you select to wait for the results, you can get synchronous behavior. On return, the system guarantees either that the timeout has been cancelled or that it has been executed to completion. The system indicates which of these possibilities has taken place by value placed in the status parameter.
If the timeout being cancelled is in progress when the call is made and the caller doesn't want synchronous behavior, NXTimeOutCancel posts a cancel request if the timeout is periodic and returns FALSE in the status parameter.
An executing timeout can cancel itself only if it is a periodic timeout. In that case, only a non synchronous cancel operation may be specified. The cancellation takes effect only after the timeout completes execution (the cancellation is detected when the system attempts to reschedule the periodic timeout).
An executing timeout can legally cancel another scheduled timeout using the synchronous or the non synchronous cancel operation. Deadlocks that result from two executing timeouts attempting to cancel each other using synchronous cancel are not handled. You must ensure that this scenario does not happen.
The following table explains various values that can be passed to wait and the related values that are returned in status:
Figure 54-1 How the wait Parameter Interacts with the status Parameter and the Timeout State
NOTE:NXTimeOutCancel does not automatically destroy (free) the timeout context being cancelled. It is the responsibility of the application to manage the timeout.
Race conditions between NXTimeOutSchedule and NXTimeOutCancel that involve the same timeout are not handled and can lead to unexpected results.
When using non synchronous cancel, you must be careful to determine exactly when the ownership of a scheduled timeout is transferred back to the application.
You must guarantee the persistence of a scheduled timeout structure until you are sure that a NXTimeOutCancel will not be called that involves the timeout structure.
On successful return, the NXTimeOut_t object can be reused.