original/man3/pthread_cleanup_push.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .TH PTHREAD_CLEANUP_PUSH 3 2008-11-24 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 pthread_cleanup_push, pthread_cleanup_pop \- push and pop
  27 thread cancellation clean-up handlers
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <pthread.h>
  31
  32 .BI "void pthread_cleanup_push(void (*" routine ")(void *),"
  33 .BI "                          void *" arg );
  34 .BI "void pthread_cleanup_pop(int " execute );
  35 .sp
  36 Compile and link with \fI\-pthread\fP.
  37 .fi
  38 .SH DESCRIPTION
  39 These functions manipulate the calling thread's stack of
  40 thread-cancellation clean-up handlers.
  41 A clean-up handler is a function that is automatically executed
  42 when a thread is canceled (or in various other circumstances
  43 described below);
  44 it might, for example, unlock a mutex so that
  45 it becomes available to other threads in the process.
  46
  47 The
  48 .BR pthread_cleanup_push ()
  49 function pushes
  50 .I routine
  51 onto the top of the stack of clean-up handlers.
  52 When
  53 .I routine
  54 is later invoked, it will be given
  55 .I arg
  56 as its argument.
  57
  58 The
  59 .BR pthread_cleanup_pop ()
  60 function removes the routine at the top of the stack of clean-up handlers,
  61 and optionally executes it if
  62 .I execute
  63 is nonzero.
  64
  65 A cancellation clean-up handler is popped from the stack
  66 and executed in the following circumstances:
  67 .IP 1. 3
  68 When a thread is canceled,
  69 all of the stacked clean-up handlers are popped and executed in
  70 the reverse of the order in which they were pushed onto the stack.
  71 .IP 2.
  72 When a thread terminates by calling
  73 .BR pthread_exit (3),
  74 all clean-up handlers are executed as described in the preceding point.
  75 (Clean-up handlers are \fInot\fP called if the thread terminates by
  76 performing a
  77 .I return
  78 from the thread start function.)
  79 .IP 3.
  80 When a thread calls
  81 .BR pthread_cleanup_pop ()
  82 with a nonzero
  83 .I execute
  84 argument, the top-most clean-up handler is popped and executed.
  85 .PP
  86 POSIX.1 permits
  87 .BR pthread_cleanup_push ()
  88 and
  89 .BR pthread_cleanup_pop ()
  90 to be implemented as macros that expand to text
  91 containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively.
  92 For this reason, the caller must ensure that calls to these
  93 functions are paired within the same function,
  94 and at the same lexical nesting level.
  95 (In other words, a clean-up handler is only established
  96 during the execution of a specified section of code.)
  97
  98 Calling
  99 .BR longjmp (3)
 100 .RB ( siglongjmp (3))
 101 produces undefined results if any call has been made to
 102 .BR pthread_cleanup_push ()
 103 or
 104 .BR pthread_cleanup_pop ()
 105 without the matching call of the pair since the jump buffer
 106 was filled by
 107 .BR setjmp (3)
 108 .RB ( sigsetjmp (3)).
 109 Likewise, calling
 110 .BR longjmp (3)
 111 .RB ( siglongjmp (3))
 112 from inside a clean-up handler produces undefined results
 113 unless the jump buffer was also filled by
 114 .BR setjmp (3)
 115 .RB ( sigsetjmp (3))
 116 inside the handler.
 117 .SH RETURN VALUE
 118 These functions do not return a value.
 119 .SH ERRORS
 120 There are no errors.
 121 .\" SH VERSIONS
 122 .\" Available since glibc 2.0
 123 .SH CONFORMING TO
 124 POSIX.1-2001.
 125 .SH NOTES
 126 On Linux, the
 127 .BR pthread_cleanup_push ()
 128 and
 129 .BR pthread_cleanup_pop ()
 130 functions \fIare\fP implemented as macros that expand to text
 131 containing \(aq\fB{\fP\(aq and \(aq\fB}\fP\(aq, respectively.
 132 This means that variables declared within the scope of
 133 paired calls to these functions will only be visible within that scope.
 134
 135 POSIX.1
 136 .\" The text was actually added in the 2004 TC2
 137 says that the effect of using
 138 .IR return ,
 139 .IR break ,
 140 .IR continue ,
 141 or
 142 .IR goto
 143 to prematurely leave a block bracketed
 144 .BR pthread_cleanup_push ()
 145 and
 146 .BR pthread_cleanup_pop ()
 147 is undefined.
 148 Portable applications should avoid doing this.
 149 .SH EXAMPLE
 150 The program below provides a simple example of the use of the functions
 151 described in this page.
 152 The program creates a thread that executes a loop bracketed by
 153 .BR pthread_cleanup_push ()
 154 and
 155 .BR pthread_cleanup_pop ().
 156 This loop increments a global variable,
 157 .IR cnt ,
 158 once each second.
 159 Depending on what command-line arguments are supplied,
 160 the main thread sends the other thread a cancellation request,
 161 or sets a global variable that causes the other thread
 162 to exit its loop and terminate normally (by doing a
 163 .IR return ).
 164
 165 In the following shell session,
 166 the main thread sends a cancellation request to the other thread:
 167
 168 .in +4n
 169 .nf
 170 $ \fB./a.out\fP
 171 New thread started
 172 cnt = 0
 173 cnt = 1
 174 Canceling thread
 175 Called clean-up handler
 176 Thread was canceled; cnt = 0
 177 .fi
 178 .in
 179
 180 From the above, we see that the thread was canceled,
 181 and that the cancellation clean-up handler was called
 182 and it reset the value of the global variable
 183 .I cnt
 184 to 0.
 185
 186 In the next run, the main program sets a
 187 global variable that causes other thread to terminate normally:
 188
 189 .in +4n
 190 .nf
 191 $ \fB./a.out x\fP
 192 New thread started
 193 cnt = 0
 194 cnt = 1
 195 Thread terminated normally; cnt = 2
 196 .fi
 197 .in
 198
 199 From the above, we see that the clean-up handler was not executed (because
 200 .I cleanup_pop_arg
 201 was 0), and therefore the value of
 202 .I cnt
 203 was not reset.
 204
 205 In the next run, the main program sets a global variable that
 206 causes the other thread to terminate normally,
 207 and supplies a nonzero value for
 208 .IR cleanup_pop_arg :
 209
 210 .in +4n
 211 .nf
 212 $ \fB./a.out x 1\fP
 213 New thread started
 214 cnt = 0
 215 cnt = 1
 216 Called clean-up handler
 217 Thread terminated normally; cnt = 0
 218 .fi
 219 .in
 220
 221 In the above, we see that although the thread was not canceled,
 222 the clean-up handler was executed, because the argument given to
 223 .BR pthread_cleanup_pop ()
 224 was nonzero.
 225 .SS Program source
 226 \&
 227 .nf
 228 #include <pthread.h>
 229 #include <sys/types.h>
 230 #include <stdio.h>
 231 #include <stdlib.h>
 232 #include <unistd.h>
 233 #include <errno.h>
 234
 235 #define handle_error_en(en, msg) \\
 236         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 237
 238 static int done = 0;
 239 static int cleanup_pop_arg = 0;
 240 static int cnt = 0;
 241
 242 static void
 243 cleanup_handler(void *arg)
 244 {
 245     printf("Called clean\-up handler\\n");
 246     cnt = 0;
 247 }
 248
 249 static void *
 250 thread_start(void *arg)
 251 {
 252     time_t start, curr;
 253
 254     printf("New thread started\\n");
 255
 256     pthread_cleanup_push(cleanup_handler, NULL);
 257
 258     curr = start = time(NULL);
 259
 260     while (!done) {
 261         pthread_testcancel();           /* A cancellation point */
 262         if (curr < time(NULL)) {
 263             curr = time(NULL);
 264             printf("cnt = %d\\n", cnt);  /* A cancellation point */
 265             cnt++;
 266         }
 267     }
 268
 269     pthread_cleanup_pop(cleanup_pop_arg);
 270     return NULL;
 271 }
 272
 273 int
 274 main(int argc, char *argv[])
 275 {
 276     pthread_t thr;
 277     int s;
 278     void *res;
 279
 280     s = pthread_create(&thr, NULL, thread_start, NULL);
 281     if (s != 0)
 282         handle_error_en(s, "pthread_create");
 283
 284     sleep(2);           /* Allow new thread to run a while */
 285
 286     if (argc > 1) {
 287         if (argc > 2)
 288             cleanup_pop_arg = atoi(argv[2]);
 289         done = 1;
 290
 291     } else {
 292         printf("Canceling thread\\n");
 293         s = pthread_cancel(thr);
 294         if (s != 0)
 295             handle_error_en(s, "pthread_cancel");
 296     }
 297
 298     s = pthread_join(thr, &res);
 299     if (s != 0)
 300         handle_error_en(s, "pthread_join");
 301
 302     if (res == PTHREAD_CANCELED)
 303         printf("Thread was canceled; cnt = %d\\n", cnt);
 304     else
 305         printf("Thread terminated normally; cnt = %d\\n", cnt);
 306     exit(EXIT_SUCCESS);
 307 }
 308 .fi
 309 .SH SEE ALSO
 310 .BR pthread_cancel (3),
 311 .BR pthread_cleanup_push_defer_np (3),
 312 .BR pthread_setcancelstate (3),
 313 .BR pthread_testcancel (3),
 314 .BR pthreads (7)