pthread_setcancelstate()--Set Cancel State

 #include <pthread.h>
 int pthread_setcancelstate(int state, int *oldstate);  

The pthread_setcancelstate() function sets the cancel state to one of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE and returns the old cancel state into the location specified by oldstate (if oldstate is non-NULL).

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

state

(Input) New cancel state (one of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE)

oldstate

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

Return Value

0

pthread_setcancelstate() was successful.

value

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

Error Conditions

If pthread_setcancelstate() 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_setcanceltype()--Set Cancel Type
  
  
• pthread_testcancel()--Create Cancellation Point

Example

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

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

void *threadfunc(void *parm)
{
  int   i = 0;
  printf("Entered secondary thread\n");
  pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
  while (1) {
    printf("Secondary thread is looping\n");
    pthread_testcancel();
    sleep(1);
    if (++i == 5) {
      /* Since default cancel type is deferred, changing the state   */
      /* will allow the next cancellation point to cancel the thread */
      printf("Cancel state set to ENABLE\n");
      pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
    }
  } /* infinite */
  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(3);

  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
Secondary thread is looping
Cancel the thread
Secondary thread is looping
Secondary thread is looping
Cancel state set to ENABLE
Main completed

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