pthread_cancel

Name

pthread_cancel -- stop and cancel a thread (not recommended)

Synopsis

       #include <rtl_signal.h>
       #include <rtl_sched.h>

       int pthread_cancel(pthread_t thread);

DESCRIPTION

This function is a standard POSIX threads function and is one of the weaker parts of the POSIX threads specification. The idea is that pthread_cancel will request termination of the target thread and this termination will either take place asynchronously or will be ignored depending on the cancel state of the target thread. If the target thread is in a DISABLED state, cancel will be pended until the thread goes to an ENABLED state. If the target thread has ENABLED it will either be in a DEFERRED or ASYNCHRONOUS mode. DEFERRED mode will defer the cancel until the thread is in a cancel point (one of a set of POSIX specified functions that correspond to states where the thread is sleeping). And so on. The semantics are complicated. Note that canceling a thread on a different processor is not supported in RTLinux.

Cancel has a bizzare effect on a thread. If the thread is accepting the cancel, it will execute whatever cancel handlers it has pushed using pthread_cleanup_push. However a canceled thread holding a mutex is not forced to cleanup the mutex lock and, in general, a canceled thread may leave a terrible mess behind. Our recommendation is to avoid the use of this function as if it were designed by a committee of software consultants rubbing their hands with glee at the huge consulting fees they would get coming in to rescue your project after the use of pthread_cancel has totally randomized the operation of your code. If cancel was not a required part of POSIX spec, we would not inflict it on our poor abused operating system. Forgive us.

RETURN VALUE

pthread_cancel returns 0 on success and a non-zero error code on error.

ERRORS

We have yet to see a good reason to use this function.

ESRCH

No thread could be found corresponding to that specified by the given thread ID.

AUTHOR

Victor Yodaiken (support@fsmlabs.com)

NOTES

pthread_cancel is safe to call from thread, and from Linux kernel code. It is not safe to call from interrupt code.

SEE ALSO

pthread_setcancelstate(3), pthread_testcancel(3)

2001 FSMLabs Inc.

All rights reserved.