pthread_cancel()--Cancel Thread

 #include <pthread.h>
 int pthread_cancel(pthread_t thread);  

The pthread_cancel() function requests cancellation of the target thread. The target thread is cancelled, based on its ability to be cancelled.

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 that is a cancellation point, or calls pthread_testcancel(), thus creating a cancellation point. When cancelability is asynchronous, all cancels are acted upon immediately, interrupting the thread with its processing.

Note: You should not use asynchronous thread cancellation through the PTHREAD_CANCEL_ASYNCHRONOUS option of pthread_setcanceltype() in your application. See the common user errors section of this document for more information.

The following functions are cancellation points:

• pthread_cond_timedwait()
• pthread_cond_wait()
• pthread_delay_np()
• pthread_join()
• pthread_join_np()
• pthread_extendedjoin_np()
• pthread_testcancel()

After action is taken for the target thread to be cancelled, the following events occur in that thread.

1. The thread calls cancellation cleanup handlers with cancellation disabled until the last cancellation cleanup handler returns. The handlers are called in Last In, First Out (LIFO) 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 cancellation cleanup handler returns, the thread is terminated and a status of PTHREAD_CANCELED is made available to any threads joining the target.
4. Any mutexes that are held by a thread that terminates, are abandoned and are no longer valid. Subsequent calls by other threads that attempt to acquire the abandoned mutex (pthread_mutex_lock() or pthread_mutex_trylock()) fail with an EOWNERTERM error.
5. Application visible process resources are not released. This includes but is not limited to mutexes, file descriptors, or any process level cleanup actions.

A cancellation cleanup handler should not exit by longjmp() or siglongjmp().

In the i5/OS implementation of threads, the initial thread is special. Termination of the initial thread by pthread_exit(), pthread_cancel() or any other thread termination mechanism terminates the entire process.

Authorities and Locks

None.

Parameters

thread

(Input) Pthread handle to the target thread

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

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_cleanup_pop()--Pop Cleanup Handler off of Cancellation Cleanup Stack
  
  
• pthread_cleanup_push()--Push Cleanup Handler onto Cancellation Cleanup Stack
  
  
• pthread_exit()--Terminate Calling Thread
  
  
• pthread_setcancelstate()--Set Cancel State
  
  
• pthread_setcanceltype()--Set Cancel Type

Example

See Code disclaimer information for information pertaining to code examples.

#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() is not 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() is not 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