VMS Help POSIX Threads, PTHREAD routines, pthread_cancel  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Allows a thread to request a thread to terminate execution.

1 - C Binding

    #include <pthread.h>

    int
    pthread_cancel (
             pthread_t   thread);

2 - Arguments

 thread

    Thread that will receive a cancelation request.

3 - Description

    This routine sends a cancelation request to the specified target
    thread. A cancelation request is a mechanism by which a calling
    thread requests the target thread to terminate as quickly as
    possible. Issuing a cancelation request does not guarantee that
    the target thread will receive or handle the request.

    When the cancelation request is acted on, all active cleanup
    handler routines for the target thread are called. When the last
    cleanup handler returns, the thread-specific data destructor
    routines are called for each thread-specific data key with a
    destructor and for which the target thread has a non-NULL value.
    Finally, the target thread is terminated.

    Note that cancelation of the target thread runs asynchronously
    with respect to the calling thread's returning from pthread_
    cancel(). The target thread's cancelability state and type
    determine when or if the cancelation takes place, as follows:

    1. The target thread can delay cancelation during critical
       operations by setting its cancelability state to PTHREAD_
       CANCEL_DISABLE.

    2. Because of communication delays, the calling thread can only
       rely on the fact that a cancelation request will eventually
       become pending in the target thread (provided that the target
       thread does not terminate beforehand).

    3. The calling thread has no guarantee that a pending cancelation
       request will be delivered because delivery is controlled by
       the target thread.

    When a cancelation request is delivered to a thread, termination
    processing is similar to that for pthread_exit(). For more
    information about thread termination, see the Thread Termination
    section of pthread_create().

    This routine is preferred in implementing an Ada abort statement
    and any other language- or software-defined construct for
    requesting thread cancelation.

    The results of this routine are unpredictable if the value
    specified in thread refers to a thread that does not currently
    exist.

4 - Return Values

    If an error condition occurs, this routine returns an integer
    indicating the type of error. Possible return values are as
    follows:

    Return      Description

    0           Successful completion.
    [EINVAL]    The specified thread is invalid.
    [ESRCH]     The thread argument does not specify an existing
                thread.

5 - Associated Routines

       pthread_cleanup_pop()
       pthread_cleanup_push()
       pthread_create()
       pthread_exit()
       pthread_join()
       pthread_setcancelstate()
       pthread_setcanceltype()
       pthread_testcancel()