linuxthreads/man/pthread_cleanup_push.man

   1 .TH PTHREAD_CLEANUP 3 LinuxThreads
   2
   3 .XREF pthread_cleanup_pop
   4 .XREF pthread_cleanup_push_defer_np
   5 .XREF pthread_cleanup_pop_restore_np
   6
   7 .SH NAME
   8 pthread_cleanup_push, pthread_cleanup_pop, pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- install and remove cleanup handlers
   9
  10 .SH SYNOPSIS
  11 #include <pthread.h>
  12
  13 void pthread_cleanup_push(void (*routine) (void *), void *arg);
  14
  15 void pthread_cleanup_pop(int execute);
  16
  17 void pthread_cleanup_push_defer_np(void (*routine) (void *), void *arg);
  18
  19 void pthread_cleanup_pop_restore_np(int execute);
  20
  21 .SH DESCRIPTION
  22
  23 Cleanup handlers are functions that get called when a thread
  24 terminates, either by calling !pthread_exit!(3) or because of
  25 cancellation. Cleanup handlers are installed and removed following a
  26 stack-like discipline.
  27
  28 The purpose of cleanup handlers is to free the resources that a thread
  29 may hold at the time it terminates. In particular, if a thread
  30 exits or is cancelled while it owns a locked mutex, the mutex will
  31 remain locked forever and prevent other threads from executing
  32 normally. The best way to avoid this is, just before locking the
  33 mutex, to install a cleanup handler whose effect is to unlock the
  34 mutex. Cleanup handlers can be used similarly to free blocks allocated
  35 with !malloc!(3) or close file descriptors on thread termination.
  36
  37 !pthread_cleanup_push! installs the |routine| function with argument
  38 |arg| as a cleanup handler. From this point on to the matching
  39 !pthread_cleanup_pop!, the function |routine| will be called with
  40 arguments |arg| when the thread terminates, either through !pthread_exit!(3)
  41 or by cancellation. If several cleanup handlers are active at that
  42 point, they are called in LIFO order: the most recently installed
  43 handler is called first.
  44
  45 !pthread_cleanup_pop! removes the most recently installed cleanup
  46 handler. If the |execute| argument is not 0, it also executes the
  47 handler, by calling the |routine| function with arguments |arg|. If
  48 the |execute| argument is 0, the handler is only removed but not
  49 executed.
  50
  51 Matching pairs of !pthread_cleanup_push! and !pthread_cleanup_pop!
  52 must occur in the same function, at the same level of block nesting.
  53 Actually, !pthread_cleanup_push! and !pthread_cleanup_pop! are macros,
  54 and the expansion of !pthread_cleanup_push! introduces an open brace !{!
  55 with the matching closing brace !}! being introduced by the expansion
  56 of the matching !pthread_cleanup_pop!.
  57
  58 !pthread_cleanup_push_defer_np! is a non-portable extension that
  59 combines !pthread_cleanup_push! and !pthread_setcanceltype!(3).
  60 It pushes a cleanup handler just as !pthread_cleanup_push! does, but
  61 also saves the current cancellation type and sets it to deferred
  62 cancellation. This ensures that the cleanup mechanism is effective
  63 even if the thread was initially in asynchronous cancellation mode.
  64
  65 !pthread_cleanup_pop_restore_np! pops a cleanup handler introduced by
  66 !pthread_cleanup_push_defer_np!, and restores the cancellation type to
  67 its value at the time !pthread_cleanup_push_defer_np! was called.
  68
  69 !pthread_cleanup_push_defer_np! and !pthread_cleanup_pop_restore_np!
  70 must occur in matching pairs, at the same level of block nesting.
  71
  72 The following sequence
  73
  74 .RS
  75 .ft 3
  76 .nf
  77 .sp
  78 pthread_cleanup_push_defer_np(routine, arg);
  79 ...
  80 pthread_cleanup_pop_defer_np(execute);
  81 .ft
  82 .LP
  83 .RE
  84 .fi
  85
  86 is functionally equivalent to (but more compact and more efficient than)
  87
  88 .RS
  89 .ft 3
  90 .nf
  91 .sp
  92 { int oldtype;
  93   pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
  94   pthread_cleanup_push(routine, arg);
  95   ...
  96   pthread_cleanup_pop(execute);
  97   pthread_setcanceltype(oldtype, NULL);
  98 }
  99 .ft
 100 .LP
 101 .RE
 102 .fi
 103
 104 .SH "RETURN VALUE"
 105
 106 None.
 107
 108 .SH ERRORS
 109
 110 None.
 111
 112 .SH AUTHOR
 113 Xavier Leroy <Xavier.Leroy@inria.fr>
 114
 115 .SH "SEE ALSO"
 116 !pthread_exit!(3),
 117 !pthread_cancel!(3),
 118 !pthread_setcanceltype!(3).
 119
 120 .SH EXAMPLE
 121
 122 Here is how to lock a mutex |mut| in such a way that it will be
 123 unlocked if the thread is canceled while |mut| is locked:
 124
 125 .RS
 126 .ft 3
 127 .nf
 128 .sp
 129 pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
 130 pthread_mutex_lock(&mut);
 131 /* do some work */
 132 pthread_mutex_unlock(&mut);
 133 pthread_cleanup_pop(0);
 134 .ft
 135 .LP
 136 .RE
 137 .fi
 138
 139 Equivalently, the last two lines can be replaced by
 140
 141 .RS
 142 .ft 3
 143 .nf
 144 .sp
 145 pthread_cleanup_pop(1);
 146 .ft
 147 .LP
 148 .RE
 149 .fi
 150
 151 Notice that the code above is safe only in deferred cancellation mode
 152 (see !pthread_setcanceltype!(3)). In asynchronous cancellation mode,
 153 a cancellation can occur between !pthread_cleanup_push! and
 154 !pthread_mutex_lock!, or between !pthread_mutex_unlock! and
 155 !pthread_cleanup_pop!, resulting in both cases in the thread trying to
 156 unlock a mutex not locked by the current thread. This is the main
 157 reason why asynchronous cancellation is difficult to use.
 158
 159 If the code above must also work in asynchronous cancellation mode,
 160 then it must switch to deferred mode for locking and unlocking the
 161 mutex:
 162
 163 .RS
 164 .ft 3
 165 .nf
 166 .sp
 167 pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
 168 pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
 169 pthread_mutex_lock(&mut);
 170 /* do some work */
 171 pthread_cleanup_pop(1);
 172 pthread_setcanceltype(oldtype, NULL);
 173 .ft
 174 .LP
 175 .RE
 176 .fi
 177
 178 The code above can be rewritten in a more compact and more
 179 efficient way, using the non-portable functions
 180 !pthread_cleanup_push_defer_np! and !pthread_cleanup_pop_restore_np!:
 181
 182 .RS
 183 .ft 3
 184 .nf
 185 .sp
 186 pthread_cleanup_push_restore_np(pthread_mutex_unlock, (void *) &mut);
 187 pthread_mutex_lock(&mut);
 188 /* do some work */
 189 pthread_cleanup_pop_restore_np(1);
 190 .ft
 191 .LP
 192 .RE
 193 .fi
 194