[Prev] [Contents] [Next]

pthread_cancel()--Cancel a Thread

Syntax

#include <pthread.h>
int pthread_cancel(pthread_t thread);
Threadsafe: Yes
Signal Safe: No

The pthread_cancel() function requests cancelation of the target thread. The target thread is canceled, based on its cancelability state.

Cancelability consists of 3 separate states (disabled, deferred, asynchronous) that can be represented by 2 boolean values.
Cancelability Cancelability State Cancelability Type
disabled PTHREAD_CANCEL_DISABLE PTHREAD_CANCEL_DEFERRED
disabled PTHREAD_CANCEL_DISABLE PTHREAD_CANCEL_ASYNCHRONOUS
deferred PTHREAD_CANCEL_ENABLE PTHREAD_CANCEL_DEFERRED
asynchronous PTHREAD_CANCEL_ENABLE PTHREAD_CANCEL_ASYNCHRONOUS

The default cancelability state is deferred.

When cancelability is disabled, all cancels are held pending in the target thread until the thread changes the cancelability. When cancelability is deferred, all cancels are held pending in the target thread until the thread changes the cancelability, calls a function which is a cancelation point or calls pthread_testcancel(), thus creating a cancelation point. When cancelability is asynchronous, all cancels are acted upon immediately, interrupting the thread with its processing.

It is recommended that your application not use asynchronous thread cancelation via the PTHREAD_CANCEL_ASYNCHRONOUS option of pthread_setcanceltype(). See the common user errors section of this document for more information.

The following functions are cancelation points:

After action is taken for the target thread is canceled, the following things occur in that thread.

  1. The thread invokes cancelation cleanup handlers with cancelation disabled until the last cancelation cleanup handler returns. The handlers are invoked in LIFO (Last In, First Out) order.
  2. Data destructors are called for any thread specific data entries that have a non NULL value for both the value and the destructor.
  3. When the last cancelation cleanup handler returns, the thread is terminated and a status of PTHREAD_CANCELED is made available to any threads joining with the target.
  4. Any mutexes that are held by a thread that terminates, become `abandoned' and are no longer valid. Subsequent calls by other threads that attempt to acquire the abandoned mutex (though pthread_mutex_lock() or pthread_mutex_trylock()) will fail with an EOWNERTERM error.
  5. No release of any application visible process resources occur. This includes but is not limited to mutexes, file descriptors, or any process level cleanup actions.
A cancelation cleanup handler should not exit via longjmp() or siglongjmp().

Note that in the OS/400 implementation of threads, the initial thread is special. Termination of the initial thread via pthread_exit(), pthread_cancel() or any other thread termination mechanism terminates the entire process.

Parameters

thread
(Input) Pthread handle to the target thread

Authorities and Locks

None.

Return Value

0
pthread_cancel() was successful.
value
pthread_cancel() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_cancel() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]
The value specified for the argument is not correct.
[ESRCH]
No thread could be found that matched the thread id specified.

Related Information

Example

#include <pthread.h>
#include <stdio.h>
#include "check.h"

void *threadfunc(void *parm)
{
  printf("Entered secondary thread\n");
  while (1) {
    printf("Secondary thread is looping\n");
    pthread_testcancel();
    sleep(1);
  }
  return NULL;
}

int main(int argc, char **argv)
{
  pthread_t             thread;
  int                   rc=0;

  printf("Entering testcase\n");
  
  /* Create a thread using default attributes */
  printf("Create thread using the NULL attributes\n");
  rc = pthread_create(&thread, NULL, threadfunc, NULL);
  checkResults("pthread_create(NULL)\n", rc);
  
  /* sleep() isn't a very robust way to wait for the thread */
  sleep(2);

  printf("Cancel the thread\n");
  rc = pthread_cancel(thread);
  checkResults("pthread_cancel()\n", rc);

  /* sleep() isn't a very robust way to wait for the thread */
  sleep(3);
  printf("Main completed\n");
  return 0;
}
Output

Entering testcase
Create thread using the NULL attributes
Entered secondary thread
Secondary thread is looping
Secondary thread is looping
Cancel the thread
Main completed


[Prev] [Contents] [Next]
Copyright © 1998, IBM Corporation. All rights reserved.
Comments? Contact
rchthrds@us.ibm.com