NXWorkCancel

Cancels a previously scheduled work.

Library:LibC
Classification:NKS
Service:Threads

Syntax

  #include <nks/thread.h> 
   
  int NXWorkCancel (
     NXWorkId_t   wid, 
     NXBool_t     wait, 
     NXBool_t    *status);

Parameters

wid

(IN) Specifies the ID of the work to be canceled.

wait

(IN) Specifies whether the caller is willing to wait to cancel the work (when the work may be active at the point of attempting to cancel it):

  • TRUE The caller is willing to wait.
  • FALSE The caller is not willing to wait.
status

(OUT) Points to the location where the status of the cancellation is to be posted. The returned value is guaranteed to be valid only if the function returns successfully.

Return Values

If successful, returns 0; otherwise, returns a nonzero error code:

Decimal

Hex

Constant

Description

9

0x09

NX_EINVAL

Invalid work ID.

Remarks

NXWorkCancel cancels a previously scheduled work. It does not cancel work in midstream, but only when the work is waiting to start execution.

By choosing to wait to cancel the work, you can get synchronous behavior. When NXWorkCancel returns, the system guarantees that the work has either been canceled or executed to completion. Once an already scheduled work context is successfully canceled using the synchronous cancel option, the work context is available for reuse and can be rescheduled by the application.

The parameter status is set to indicated the status of the cancel operation. The value is guaranteed to be valid only if the call returns successfully. See the following table for the possible values and their meaning:

Figure 53-1 How the wait Parameter Interacts with the status Parameter

An executing work can cancel itself only if it is periodic work, and then only the non-synchronous cancel operation can be specified. The cancellation takes effect only after the work context completes execution (and the cancellation is detected when the system attempts to reschedule the periodic work context).

An executing work context can legally cancel another scheduled work context using the synchronous or the non-synchronous cancel operation. Deadlocks that result from two executing work contexts attempting to cancel each other using the synchronous cancel operation are not handled. It is the application's responsibility to ensure that this doesn't happen.

NXWorkCancel does not automatically free the work context being canceled. The application must manage the work context.

See Also