ChorusOS man pages section 3POSIX: POSIX Library Functions

cancellation(3POSIX)

NAME

cancellation- overview of concepts related to POSIX thread cancellation

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

DESCRIPTION

FUNCTION	ACTION
`pthread_cancel`	Cancels thread execution.
`pthread_setcancelstate`	Sets the cancellation state of a thread.
`pthread_setcanceltype`	Sets the cancellation type of a thread.
`pthread_testcancel`	Creates a cancellation point in the calling thread.
`pthread_cleanup_push`	Pushes a cleanup handler routine.
`pthread_cleanup_pop`	Pops a cleanup handler routine.

Cancellation

Thread cancellation allows a thread to terminate the execution of any application thread in the process. Cancellation is useful when further operation of one or more threads is undesirable or unnecessary.

An example of a situation that would benefit from using cancellation is an asynchronously-generated cancel condition such as a user requesting to close or exit some running operation. Another example is the completion of a task undertaken by a number of threads, such as solving a maze. With many threads searching for the solution, one of the threads might solve the puzzle while the others continue to operate. Since they are serving no purpose at that point, they should all be canceled.

Planning

Planning and programming for most cancellations follow this pattern:

Identify which threads you want to cancel, and insert pthread_cancel(3POSIX) statements.
Identify system-defined cancellation points where a thread that might be canceled could have changed a system or program state that should be restored. See the Cancellation Points for a list.
When a thread changes the system or program state just before a cancellation point, and should restore that state before the thread is canceled, place a cleanup handler before the cancellation point with pthread_cleanup_push(3POSIX). Wherever a thread restores the changed state, pop the cleanup handler from the cleanup stack with pthread-cleanup-pop(3POSIX).
Know whether the threads you are canceling call into cancel-unsafe libraries, and disable cancellation with pthread_setcancelstate(3POSIX) before the call into the library. See Cancellation State.
To cancel a thread in a procedure that contains no cancellation points, insert your own cancellation points with pthread_testcancel(3POSIX). pthread_testcancel() creates cancellation points by testing for pending cancellations and performing those cancellations if they are found. Push and pop cleanup handlers around the cancellation point, if necessary (see Step 3, above).

Cancellation Points

The system defines certain points at which cancellation can occur (cancellation points). You can create additional cancellation points in your application with pthread_testcancel(3POSIX).

The following cancellation points are defined by the system (system-defined cancellation points):

accept(2POSIX), close(2POSIX), connect(2POSIX), creat(2POSIX), listen(2POSIX), mq_receive(2POSIX), mq_send(2POSIX), open(2POSIX), pause(3POSIX), poll(2POSIX), pthread_cond_timedwait(3POSIX), pthread_cond_wait(3POSIX), pthread_join(3POSIX), pthread_testcancel(3POSIX), read(2POSIX), readv(2POSIX), recvfrom(2POSIX), recvmsg(2POSIX), select(2POSIX), sem_wait(3POSIX), connect(2POSIX), sendto(2POSIX), sendmsg(2POSIX), sigwaitinfo(2POSIX), sigsuspend(2POSIX), sigtimedwait(2POSIX), sigwait(2POSIX), sleep(1M), wait(2POSIX), waitpid(2POSIX), write(2POSIX), writev(2POSIX), and fcntl(2POSIX), when specifying F_SETLKW as the command.

When cancellation is asynchronous, it can occur before, during, or after the execution of the function defined as the cancellation point. When cancellation is deferred (the default case), it occurs before the function defined as the cancellation point executes. See Cancellation Type for more information about deferred and asynchronous cancellation.

Choosing where to place cancellation points and understanding how cancellation affects your program depend upon your understanding of both your application and of cancellation mechanics.

Typically, any call that might require a long wait should be a cancellation point. Operations need to check for pending cancellation requests when the operation is about to block indefinitely. This includes threads waiting in pthread_cond_wait(3POSIX) and pthread_cond_timedwait(3POSIX), threads waiting for the termination of another thread in pthread_join(3POSIX), and threads blocked on sigwait(2POSIX).

A mutex is explicitly not a cancellation point and should be held for only the minimal essential time.

Most of the dangers in performing cancellations deal with restoring invariants and freeing shared resources properly. For example, a carelessly canceled thread might leave a mutex in a locked state, leading to a deadlock. Alternatively, it might leave a region of memory allocated with no way to identify it and therefore no way to free it.

Cleanup Handlers

When a thread is canceled, it should release resources and clean up the state that is shared with other threads. So, whenever a thread that might be canceled changes the state of the system or of the program, be sure to push a cleanup handler with pthread_cleanup_push(3POSIX) before the cancellation point.

When a thread is canceled, all the currently-stacked cleanup handlers are executed in last-in-first-out (LIFO) order. Each handler is run in the scope in which it was pushed. When the last cleanup handler returns, the thread-specific data destructor functions are called. Thread execution terminates when the last destructor function returns.

When, in the normal course of the program, an uncanceled thread restores the state that it had previously changed, be sure to pop the cleanup handler (that you had set up where the change took place) using pthread_cleanup_pop(3POSIX). This way, if the thread is canceled later, only the currently-changed state will be restored by the handlers that are left in the stack.

Be sure to pop the handler in the same scope in which it was pushed. Also, make sure that each push statement has a matching pop statement, or compiler errors will be generated.

Cancellation State

Most programmers will use only the default cancellation state of PTHREAD_CANCEL_ENABLE, but can choose to change the state, using pthread_setcancelstate(3POSIX), which determines whether a thread may be canceled at all. With the default state of PTHREAD_CANCEL_ENABLE, cancellation is enabled, and the thread may be canceled at points determined by its cancellation type. See Cancellation Type.

If the state is PTHREAD_CANCEL_DISABLE, cancellation is disabled, and the thread may not be canceled at any point -- all cancellation requests to it are held pending.

You might want to disable cancellation before a call to a cancel-unsafe library, restoring the old cancel state when the call returns from the library.

Cancellation Type

A thread's cancellation type is set with pthread_setcanceltype(3POSIX), and determines whether the thread can be canceled anywhere in its execution, or only at cancellation points.

With the default type of PTHREAD_CANCEL_DEFERRED, the thread may be canceled only at cancellation points, and then only when cancellation is enabled.

If the type is PTHREAD_CANCEL_ASYNCHRONOUS, the thread may be canceled at any point in its execution (provided that cancellation is enabled). Try to limit regions of asynchronous cancellation to sequences with no external dependencies that could result in dangling resources or unresolved state conditions. Using asynchronous cancellation is discouraged because of the danger involved in trying to guarantee correct cleanup handling at absolutely every point in the program.

Cancellation Type/State Table
Type	State
	Enabled (Default)	Disabled
Deferred (Default)	Cancellation occurs when the target thread reaches a cancellation point and a cancel is pending. (Default)	All cancellation requests to the target thread are held pending.
Asynchronous	Receipt of a `pthread_cancel`(3POSIX) call causes immediate cancellation.	All cancellation requests to the target thread are held pending; as soon as cancellation is re-enabled, pending cancellations are executed immediately.

EXAMPLES - POSIX Threads Only

Example 1 The following short C++ example shows the pushing/popping of cancellation handlers, the disabling/enabling of cancellation, and the use of `pthread_testcancel()`. The `free_res()` cancellation handler in this example is a dummy function that simply prints a message, but that would free resources in a real application. The function `f2()` is called from the main thread, and goes deep into its call stack by calling itself recursively.

Before f2() starts running, the newly created thread has probably posted a cancellation on the main thread since the main thread calls pthread_yield() directly after creating thread2. Because cancellation was initially disabled in the main thread, through a call to pthread_setcancelstate(), the call to f2() from main() continues and constructs X at each recursive call, even though the main thread has a pending cancellation.

When f2() is called for the fifty-first time (when "i == 50"), f2() enables cancellation by calling pthread_setcancelstate(). It then establishes a cancellation point for itself by calling pthread_testcancel(). (Because a cancellation is pending, a call to a cancellation point such as read(2POSIX) or write(2POSIX) would also cancel the caller here.)

After the main() thread is canceled at the fifty-first iteration, all the cleanup handlers that were pushed are called in sequence; this is indicated by the calls to free_res() and the calls to the destructor for X. At each level, the C++ runtime calls the destructor for X and then the cancellation handler, free_res(). The print messages from free_res() and X's destructor show the sequence of calls.

At the end, the main thread is joined by thread2. Because the main thread was canceled, its return status from pthread_join() is PTHREAD_CANCELED. After the status is printed, thread2 returns, killing the process (since it is the last thread in the process).

#include <pthread.h>
#include <sched.h>
extern "C" void pthread_yield(void); 
 
extern "C" void printf(...);
 
struct X {
                int x;   
                X(int i){x = i; printf("X(%d) constructed.\n", i);}
                ~X(){ printf("X(%d) destroyed.\n", x);}
};
 
void
free_res(void *i)
{
                printf("Freeing `%d`\n",i);
}

char* f2(int i)  
{
                try {
                X dummy(i);
                pthread_cleanup_push(free_res, (void *)i);
                if (i == 50) {
                       pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
                    pthread_testcancel();
                }
                f2(i+1); 
                pthread_cleanup_pop(0);  
                }
                catch (int) {
                printf("Error: In handler.\n");
                }
                return "f2";
}

void *   
thread2(void *tid)
{
                void *sts;

                printf("I am new thread :%d\n", pthread_self());

                pthread_cancel((pthread_t)tid);
 
                pthread_join((pthread_t)tid, &sts);
 
                printf("main thread cancelled due to %d\n", sts);
 
                return (sts);
}
 
main()
{
                pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
                pthread_create(NULL, NULL, thread2, (void *)pthread_self());
                pthread_yield();
                printf("Returned from %s\n",f2(0));
}

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving