Marks the specified thread so it exits as soon as it reaches a cancellation point.
#include <nks/thread.h>
int NXThreadDestroy (
NXThreadId_t tid);
(IN) Specifies the ID of the thread to mark for termination.
If successful, returns 0; otherwise, returns a nonzero error code:
NXThreadDestroy marks the specified thread such that it exits as soon as it reaches a cancellation point, usually another NKS call. This function does not block while it waits for the target thread to be destroyed. Because the next cancellation point is not predictable, the latency of this process cannot be defined. Destroying a thread that has already been destroyed has no effect but does return an error.
IMPORTANT:A thread cannot destroy itself. The proper way to exit is to call NXThreadExit.
A cancellation point is a function in the NKS library where the calling thread is checked for a state change such as suspend or destroy. If the thread is marked to exit, the thread does not proceed from that point, but instead blocks and NKS destroys it. Almost all NKS functions contain at least one cancellation point, but applications can explicitly set up cancellation checks by calling NXThreadYield.
NXThreadDestroy does not honor the state set by calling nxCancelDisable. The thread is killed regardless of what it is doing at the time it reaches the next cancellation point.
NXThreadInterrupt is the preferred function to call to terminate a thread. The NXThreadDestroy function, which is not the preferred function, has been provided for completeness and to simplify the implementation of ported code that is already using a thread cancel function.
Some applications may tolerate one thread exiting while holding a mutex, especially those that profit from the relative anonymity an NKS thread enjoys. These applications generally create states that migrate from thread to thread, with each thread performing a small defined amount of work (which might include holding locks that get released during work that is executed by a subsequent thread). In general, it is incorrect to kill a thread that holds a lock or another resource.