pthread_cleanup_push()

Push cancellation cleanup handler

Synopsis:

#include <pthread.h>

void pthread_cleanup_push( void* (routine)(void*),
                           void* arg );

Library:

libc

Description:

The pthread_cleanup_push() function pushes the cancellation cleanup handler routine onto the calling thread's cancellation cleanup stack.

The cancellation cleanup handler is popped from the stack and invoked with argument arg when:

• The thread exits (calls pthread_exit()).
• The thread acts upon a cancellation request.
• The thread calls pthread_cleanup_pop() with a nonzero argument.

Because the pthread_cleanup_push() function is implemented as a macro it must be paired with pthread_cleanup_pop() within the same lexical scope.

Examples:

This example shows how a cancellation cleanup handler can be used to free resources, such as a mutex, when a thread is terminated.

#include <pthread.h>

pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;

void unlock( void * arg )
{
   pthread_mutex_unlock( &lock );
}

void * function( void * arg )
{
   while( 1 )
   {
      pthread_mutex_lock( &lock );
      pthread_cleanup_push( &unlock, NULL );

      /*
       Any of the possible cancellation points could
       go here.
      */
      pthread_testcancel();

      pthread_cleanup_pop( 1 );
   }
}

Classification:

POSIX 1003.1 (Threads)

See also:

pthread_cleanup_pop(), pthread_cancel().