← Back to branch summary

~ubuntu-branches/ubuntu/utopic/eglibc/utopic

« back to all changes in this revision

Viewing changes to .pc/all/local-pthread-manpages.diff/linuxthreads/man/pthread_cleanup_push.man

  • Committer: Package Import Robot
  • Author(s): Adam Conrad
  • Date: 2012-10-26 05:14:58 UTC
  • mfrom: (1.5.1) (4.4.22 experimental)
  • Revision ID: package-import@ubuntu.com-20121026051458-oryotr4i03ob5pab
Tags: 2.16-0ubuntu1
* Merge with unreleased 2.16 in Debian experimental, remaining changes:
  - Drop the Breaks line from libc6, which refers to a Debian transition
  - Remove the libc6 recommends on libc6-i686, which we don't build
  - Enable libc6{,-dev}-armel on armhf and libc6{-dev}-armhf on armel
  - Ship update-locale and validlocale in /usr/sbin in libc-bin
  - Don't build locales or locales-all in Ubuntu, we rely on langpacks
  - Heavily mangle the way we do service restarting on major upgrades
  - Use different MIN_KERNEL_SUPPORTED versions than Debian, due to
    buildd needs.  This should be universally bumped to 3.2.0 once all
    our buildds (including the PPA guests) are running precise kernels
  - Build i386 variants as -march=i686, build amd64 with -O3, and build
    ppc64 variants (both 64-bit and 32-bit) with -O3 -fno-tree-vectorize
  - Re-enable unsubmitted-ldconfig-cache-abi.diff and rebuild the cache
    on upgrades from previous versions that used a different constant
  - debian/patches/any/local-CVE-2012-3406.diff: switch to malloc when
    array grows too large to handle via alloca extension (CVE-2012-3406)
  - Build generic i386/i686 flavour with -mno-tls-direct-seg-refs
* Changes added/dropped with this merge while reducing our delta:
  - Stop building glibc docs from the eglibc source, and instead make
    the glibc-docs stub have a hard dependency on glibc-doc-reference
  - Remove outdated conflicts against ancient versions of ia32-libs
  - Drop the tzdata dependency from libc6, it's in required and minimal
  - Use gcc-4.7/g++-4.7 by default on all our supported architectures
  - Save our historical changelog as changelog.ubuntu in the source
  - Drop nscd's libaudit build-dep for now, as libaudit is in universe
  - Drop the unnecessary Breaks from libc6 to locales and locales-all
  - Ship xen's ld.so.conf.d snippet as /etc/ld.so.conf.d/libc6-xen.conf
* Disable hard failures on the test suite for the first upload to raring

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/all/local-pthread-manpages.diff/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