ThreadDestroy(), ThreadDestroy

Destroy a thread immediately

Synopsis:

#include <sys/neutrino.h>

int ThreadDestroy( int tid,
                   int priority,
                   void* status );

int ThreadDestroy_r( int tid,
                     int priority,
                     void* status );

Arguments:

tid: The ID of the thread that you want to destroy, as returned by ThreadCreate(), or 0 to destroy the current thread, or -1 to destroy all threads in the current process.
priority: The priority at which you want to destroy multiple threads, or -1 to use the priority of the current thread.
status: The value to make available to a thread that joins a nondetached thread that's destroyed.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

These kernel calls terminate the thread specified by tid. If tid is 0, the calling thread is assumed. If tid is -1, all of the threads in the process are destroyed. When multiple threads are destroyed, the destruction is scheduled one thread at a time at the priority specified by the priority argument. If priority is -1, then the priority of the calling thread is used.

The ThreadDestroy() and ThreadDestroy_r() functions are identical, except in the way they indicate errors. See the Returns section for details.

Note: Instead of using these kernel calls directly, consider calling pthread_exit(). The behavior of POSIX calls following a call to ThreadDestroy() or ThreadDestroy_r() is undefined.

If a terminated thread isn't detached, it makes the value specified by the status argument available to any successful join on it (through pthread_join()). Until another thread retrieves this value, the thread ID tid isn't reused, and a small kernel resource (a thread object) is held in the system. If the thread is detached, then status is ignored, and all thread resources are immediately released.

(QNX Neutrino 7.0.1 or later) Any event that you registered for the thread with the _NTO_TCTL_ADD_EXIT_EVENT ThreadCtl() command is delivered when the thread is terminated.

When the last thread in a process is destroyed, the process terminates and all thread resources are released, even for threads that haven't been detached or joined.

Note: On return from ThreadDestroy() or ThreadDestroy_r(), the target thread is marked for death, but if it isn't possible to kill it immediately, it may not be terminated until it attempts to run.

Blocking states

If these calls return, they don't block.

Returns:

If the calling thread is destroyed, ThreadDestroy() and ThreadDestroy_r() don't return.

The only difference between these functions is the way they indicate errors:

ThreadDestroy(): If this function returns and an error occurs, -1 is returned and errno is set. Any other value returned indicates success.
ThreadDestroy_r(): EOK is returned on success. This function does NOT set errno. If this function returns and an error occurs, any value in the Errors section may be returned.

Errors:

ESRCH: The thread indicated by tid doesn't exist.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes

ThreadDestroy(), ThreadDestroy_r()