pthread_setcanceltype()--Set Cancel Type

 #include <pthread.h>
 int pthread_setcanceltype(int type, int *oldtype);  

The pthread_setcanceltype() function sets the cancel type to one of PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS and returns the old cancel type into the location specified by oldtype (if oldtype is non-NULL)

Cancelability consists of 3 separate states (disabled, deferred, asynchronous) that can be represented by 2 boolean values.

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 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: It is recommended that your application not use asynchronous thread cancellation through the PTHREAD_CANCEL_ASYNCHRONOUS option of pthread_setcanceltype(). See the common user errors section of this document for more information.

Authorities and Locks

None.

Parameters

type

(Input) New cancel type (one of PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS) 

oldtype

(Output) Address of variable to contain old cancel type. (NULL is allowed)

Return Value

0

pthread_setcanceltype() was successful.

value

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

Error Conditions

If pthread_setcanceltype() 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.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_cancel()--Cancel Thread
  
  
• pthread_exit()--Terminate Calling Thread
  
  
• pthread_setcancelstate()--Set Cancel State
  
  
• pthread_testcancel()--Create Cancellation Point

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

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

pthread_mutex_t    mutex = PTHREAD_MUTEX_INITIALIZER;

void cleanupHandler(void *parm)
{
  int rc;
  printf("Inside cleanup handler, unlock mutex\n");
  rc = pthread_mutex_unlock((pthread_mutex_t *)parm);
  checkResults("pthread_mutex_unlock\n", rc);
}

void *threadfunc(void *parm)
{
  int            rc;
  int            oldtype;

  printf("Entered secondary thread, lock mutex\n");
  rc = pthread_mutex_lock(&mutex);
  checkResults("pthread_mutex_lock()\n", rc);

  pthread_cleanup_push(cleanupHandler, &mutex);
  /* We must assume there is a good reason for async. cancellability   */
  /* and also, we must assume that if we get interrupted, it is        */
  /* appropriate to unlock the mutex. More than likely it is not       */
  /* because we will have left some data structures in a strange state */
  /* if we are async. interrupted while holding the mutex              */
  rc = pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldtype);
  checkResults("pthread_setcanceltype()\n", rc);
 
  printf("Secondary thread is now looping\n");
  while (1) { sleep(1); }
  printf("Unexpectedly got out of loop!\n");
  pthread_cleanup_pop(0);
  return NULL;
}

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

  printf("Enter Testcase - %s\n", argv[0]);

  /* 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(1);

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

  rc = pthread_join(thread, &status);
  if (status != PTHREAD_CANCELED) {
    printf("Unexpected thread status\n");
    exit(1);
  }
  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPSETCANT0
Create thread using the NULL attributes
Entered secondary thread, lock mutex
Secondary thread is now looping
Cancel the thread
Inside cleanup handler, unlock mutex
Main completed

[ Back to top | Pthread APIs | APIs by category ]