ThreadCancel(), ThreadCancel_r()

Cancel a thread

Synopsis:

#include <sys/neutrino.h>

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

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

Description:

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

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. When the cancellation is acted upon, the thread jumps to the location specified by canstub. This stub should call cancellation cleanup handlers for the thread. When the last cancellation cleanup handler returns, the stub must terminate the thread using:

ThreadDestroy( 0, -1, PTHREAD_CANCEL);

You must provide a canstub function.

Unlike ThreadDestroy(), which destroys a thread immediately, ThreadCancel() is used to request the target thread to execute cleanup code and then terminate at its earliest convenience.

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 any of the calls defined in the table below. All kernel calls that block are cancellation points with the exception of MsgSendvnc() and SyncMutexLock().
Enabled	Async	Cancellation happens immediately.

The state is set using pthread_setcancelstate(), and the type is set using pthread_setcanceltype().

The following POSIX 1003.1 and C standard functions are cancellation points. Note that other functions not listed here 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():

close()
closedir()
creat()

fclose()
fcntl()
fflush()
fgetc()
fgets()
fopen()
fprintf()
fputc()
fputs()
fread()
freopen()
fscanf()
fseek()
ftell()
fwrite()

getc()
getchar()
getcwd()
getgrgid()
getgrnam()
getlogin()
getpwnam()
gets()

lseek()

mq_receive()
mq_send()

nanosleep()

open()
opendir()

pause()
perror()
printf()
pthread_cond_timedwait()
pthread_cond_wait()
pthread_join()
pthread_testcancel()
putc()
putchar()
puts()

read()
readdir()
remove()
rename()
rewind()
rewinddir()

scanf()
sem_wait()
sigsuspend()
sigtimedwait()
sigwaitinfo()
sleep()
system()

tcdrain()
tmpfile()
tmpnam()
ttyname()

ungetc()
unlink()

wait()
waitpid()
write()

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, -1 is returned and errno is set. 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 6

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