summary refs log tree commit diff
path: root/linuxthreads/man/pthread_cleanup_push.man
diff options
context:
space:
mode:
Diffstat (limited to 'linuxthreads/man/pthread_cleanup_push.man')
-rw-r--r--linuxthreads/man/pthread_cleanup_push.man194
1 files changed, 0 insertions, 194 deletions
diff --git a/linuxthreads/man/pthread_cleanup_push.man b/linuxthreads/man/pthread_cleanup_push.man
deleted file mode 100644
index 1591431c9c..0000000000
--- a/linuxthreads/man/pthread_cleanup_push.man
+++ /dev/null
@@ -1,194 +0,0 @@
-.TH PTHREAD_CLEANUP 3 LinuxThreads
-
-.XREF pthread_cleanup_pop
-.XREF pthread_cleanup_push_defer_np
-.XREF pthread_cleanup_pop_restore_np
-
-.SH NAME
-pthread_cleanup_push, pthread_cleanup_pop, pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- install and remove cleanup handlers
-
-.SH SYNOPSIS
-#include <pthread.h>
-
-void pthread_cleanup_push(void (*routine) (void *), void *arg);
-
-void pthread_cleanup_pop(int execute);
-
-void pthread_cleanup_push_defer_np(void (*routine) (void *), void *arg);
-
-void pthread_cleanup_pop_restore_np(int execute);
-
-.SH DESCRIPTION
-
-Cleanup handlers are functions that get called when a thread
-terminates, either by calling !pthread_exit!(3) 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 cancelled 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!(3) or close file descriptors on thread termination.
-
-!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!(3)
-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.
-
-!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!.
-
-!pthread_cleanup_push_defer_np! is a non-portable extension that
-combines !pthread_cleanup_push! and !pthread_setcanceltype!(3).
-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.
-
-!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 following sequence
-
-.RS
-.ft 3
-.nf
-.sp
-pthread_cleanup_push_defer_np(routine, arg);
-...
-pthread_cleanup_pop_defer_np(execute);
-.ft
-.LP
-.RE
-.fi
-
-is functionally equivalent to (but more compact and more efficient than)
-
-.RS
-.ft 3
-.nf
-.sp
-{ int oldtype;
-  pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
-  pthread_cleanup_push(routine, arg);
-  ...
-  pthread_cleanup_pop(execute);
-  pthread_setcanceltype(oldtype, NULL);
-}
-.ft
-.LP
-.RE
-.fi
-
-.SH "RETURN VALUE"
-
-None.
-
-.SH ERRORS
-
-None.
-
-.SH AUTHOR
-Xavier Leroy <Xavier.Leroy@inria.fr>
-
-.SH "SEE ALSO"
-!pthread_exit!(3),
-!pthread_cancel!(3),
-!pthread_setcanceltype!(3).
-
-.SH EXAMPLE
-
-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:
-
-.RS
-.ft 3
-.nf
-.sp
-pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
-pthread_mutex_lock(&mut);
-/* do some work */
-pthread_mutex_unlock(&mut);
-pthread_cleanup_pop(0);
-.ft
-.LP
-.RE
-.fi
-
-Equivalently, the last two lines can be replaced by
-
-.RS
-.ft 3
-.nf
-.sp
-pthread_cleanup_pop(1);
-.ft
-.LP
-.RE
-.fi
-
-Notice that the code above is safe only in deferred cancellation mode
-(see !pthread_setcanceltype!(3)). 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:
-
-.RS
-.ft 3
-.nf
-.sp
-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);
-.ft
-.LP
-.RE
-.fi
-
-The code above can be rewritten in a more compact and more
-efficient way, using the non-portable functions
-!pthread_cleanup_push_defer_np! and !pthread_cleanup_pop_restore_np!:
-
-.RS
-.ft 3
-.nf
-.sp
-pthread_cleanup_push_restore_np(pthread_mutex_unlock, (void *) &mut);
-pthread_mutex_lock(&mut);
-/* do some work */
-pthread_cleanup_pop_restore_np(1);
-.ft
-.LP
-.RE
-.fi
-