ThreadCancel(), ThreadCancel_r()

Updated: April 19, 2023

Cancel a thread

Synopsis:

#include <sys/neutrino.h>

int ThreadCancel( int tid,
                  void (*canstub)(void) );

int ThreadCancel_r( int tid,
                    void (*canstub)(void) );

Arguments:

tid
The ID of the thread that you want to cancel, as returned by ThreadCreate().
canstub
A pointer to the location that you want the thread to jump to when the cancellation occurs; see below.
Note: You must provide a canstub function.

Library:

libc

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

Description:

These kernel calls request that the thread specified by tid be canceled. The target thread's cancelability state and type determine when the cancellation takes effect.

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

Note: Don't use these kernel calls directly; use pthread_cancel() instead.

Unlike ThreadDestroy(), which destroys a thread immediately, ThreadCancel() allows you to provide a function (canstub) that requests that the target thread execute any cleanup code and then terminate at its earliest convenience.

When the cancellation is acted upon, the thread jumps to the location specified by canstub. This stub function must terminate the thread. The best way to do this is with pthread_exit(), which runs all defined cancellation handlers and performs data cleanup. With pthread_exit(), the stub function can make any value available to any thread joining the thread that it's terminating, as in this example that uses PTHREAD_CANCELED:
pthread_exit( PTHREAD_CANCELED );

The cancellation processing in the target thread runs asynchronously with respect to the calling thread, which doesn't block.

The combinations of cancelability state and type are as follows:

State Type Description
Disabled Deferred Cancel requests are made pending.
Disabled Async Cancel requests are made pending.
Enabled Deferred Cancellation happens at the next cancellation point. These are at explicitly coded calls to pthread_testcancel() or an attempt to enter a blocking state in certain calls (see below). All kernel calls that block are cancellation points, with the exception of MsgSendvnc() and SyncMutexLock().
Enabled Async Cancellation happens immediately.

Use pthread_setcancelstate(), and pthread_setcanceltype() to set the state and type.

POSIX defines a list of functions that are cancellation points; some functions that aren't listed there may also be cancellation points. Any function that calls a blocking kernel call that's a cancellation point will itself become a cancellation point when the kernel call is made. The most common blocking kernel call in library code is MsgSendv().

Blocking states

These calls don't block.

Returns:

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

ThreadCancel()
If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.
ThreadCancel_r()
EOK is returned on success. This function does NOT set errno. If 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