GNU Info

(libc.info)Cleanup Handlers

---

Next: Mutexes Prev: Cancellation Up: POSIX Threads

---

Enter node , (file) or (file)node

Cleanup Handlers
================

   Cleanup handlers are functions that get called when a thread
terminates, either by calling `pthread_exit' or because of
cancellation. Cleanup handlers are installed and removed following a
stack-like discipline.

   The purpose of cleanup handlers is to free the resources that a
thread may hold at the time it terminates. In particular, if a thread
exits or is canceled while it owns a locked mutex, the mutex will
remain locked forever and prevent other threads from executing
normally. The best way to avoid this is, just before locking the mutex,
to install a cleanup handler whose effect is to unlock the mutex.
Cleanup handlers can be used similarly to free blocks allocated with
`malloc' or close file descriptors on thread termination.

   Here is how to lock a mutex MUT in such a way that it will be
unlocked if the thread is canceled while MUT is locked:

     pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
     pthread_mutex_lock(&mut);
     /* do some work */
     pthread_mutex_unlock(&mut);
     pthread_cleanup_pop(0);

   Equivalently, the last two lines can be replaced by

     pthread_cleanup_pop(1);

   Notice that the code above is safe only in deferred cancellation mode
(see `pthread_setcanceltype'). In asynchronous cancellation mode, a
cancellation can occur between `pthread_cleanup_push' and
`pthread_mutex_lock', or between `pthread_mutex_unlock' and
`pthread_cleanup_pop', resulting in both cases in the thread trying to
unlock a mutex not locked by the current thread. This is the main
reason why asynchronous cancellation is difficult to use.

   If the code above must also work in asynchronous cancellation mode,
then it must switch to deferred mode for locking and unlocking the
mutex:

     pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
     pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
     pthread_mutex_lock(&mut);
     /* do some work */
     pthread_cleanup_pop(1);
     pthread_setcanceltype(oldtype, NULL);

   The code above can be rewritten in a more compact and efficient way,
using the non-portable functions `pthread_cleanup_push_defer_np' and
`pthread_cleanup_pop_restore_np':

     pthread_cleanup_push_defer_np(pthread_mutex_unlock, (void *) &mut);
     pthread_mutex_lock(&mut);
     /* do some work */
     pthread_cleanup_pop_restore_np(1);

 - Function: void pthread_cleanup_push (void (*ROUTINE) (void *), void
          *ARG)
     `pthread_cleanup_push' installs the ROUTINE function with argument
     ARG as a cleanup handler. From this point on to the matching
     `pthread_cleanup_pop', the function ROUTINE will be called with
     arguments ARG when the thread terminates, either through
     `pthread_exit' or by cancellation. If several cleanup handlers are
     active at that point, they are called in LIFO order: the most
     recently installed handler is called first.

 - Function: void pthread_cleanup_pop (int EXECUTE)
     `pthread_cleanup_pop' removes the most recently installed cleanup
     handler. If the EXECUTE argument is not 0, it also executes the
     handler, by calling the ROUTINE function with arguments ARG. If
     the EXECUTE argument is 0, the handler is only removed but not
     executed.

   Matching pairs of `pthread_cleanup_push' and `pthread_cleanup_pop'
must occur in the same function, at the same level of block nesting.
Actually, `pthread_cleanup_push' and `pthread_cleanup_pop' are macros,
and the expansion of `pthread_cleanup_push' introduces an open brace
`{' with the matching closing brace `}' being introduced by the
expansion of the matching `pthread_cleanup_pop'.

 - Function: void pthread_cleanup_push_defer_np (void (*ROUTINE) (void
          *), void *ARG)
     `pthread_cleanup_push_defer_np' is a non-portable extension that
     combines `pthread_cleanup_push' and `pthread_setcanceltype'.  It
     pushes a cleanup handler just as `pthread_cleanup_push' does, but
     also saves the current cancellation type and sets it to deferred
     cancellation. This ensures that the cleanup mechanism is effective
     even if the thread was initially in asynchronous cancellation mode.

 - Function: void pthread_cleanup_pop_restore_np (int EXECUTE)
     `pthread_cleanup_pop_restore_np' pops a cleanup handler introduced
     by `pthread_cleanup_push_defer_np', and restores the cancellation
     type to its value at the time `pthread_cleanup_push_defer_np' was
     called.

   `pthread_cleanup_push_defer_np' and `pthread_cleanup_pop_restore_np'
must occur in matching pairs, at the same level of block nesting.

   The sequence

     pthread_cleanup_push_defer_np(routine, arg);
     ...
     pthread_cleanup_pop_defer_np(execute);

is functionally equivalent to (but more compact and efficient than)

     {
       int oldtype;
       pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
       pthread_cleanup_push(routine, arg);
       ...
       pthread_cleanup_pop(execute);
       pthread_setcanceltype(oldtype, NULL);
     }