ThreadDestroy(), ThreadDestroy_r()

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 the 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 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.

---

Instead of using these kernel calls directly, consider calling pthread_abort() or pthread_exit()

---

If a terminated thread isn't detached, it makes the value specified by the status argument available to any successful join on it. 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.

When the last thread in a process is destroyed, the process terminates, and all thread resources are released, even if they're not detached and unjoined.

---

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

See also:

pthread_abort(), pthread_exit(), ThreadCancel(), ThreadCreate()