This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
[PATCH] Create nptl manual node and document thread_local limitation
- From: Siddhesh Poyarekar <siddhesh at redhat dot com>
- To: libc-alpha at sourceware dot org
- Date: Wed, 20 Feb 2013 17:23:35 +0530
- Subject: [PATCH] Create nptl manual node and document thread_local limitation
Hi,
The patch below adds a chapter on threads and documents the fact that
destructors for thread-specific data created with pthread_key_create
should not use thread_local objects.
Siddhesh
* manual/Makefile (chapters): Add nptl.
* manual/debug.texi (Debugging Support): Add link to Threads
chapter.
* manual/nptl.texi: New file.
diff --git a/manual/Makefile b/manual/Makefile
index c1a304c..10314a9 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -42,7 +42,7 @@ chapters = $(addsuffix .texi, \
message search pattern io stdio llio filesys \
pipe socket terminal syslog math arith time \
resource setjmp signal startup process job nss \
- users sysinfo conf crypt debug)
+ users sysinfo conf crypt debug nptl)
add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
appendices = lang.texi header.texi install.texi maint.texi platform.texi \
contrib.texi
diff --git a/manual/debug.texi b/manual/debug.texi
index b2bcb31..79dc70c 100644
--- a/manual/debug.texi
+++ b/manual/debug.texi
@@ -1,5 +1,5 @@
@node Debugging Support
-@c @node Debugging Support, , Cryptographic Functions, Top
+@c @node Debugging Support, Threads, Cryptographic Functions, Top
@c %MENU% Functions to help debugging applications
@chapter Debugging support
diff --git a/manual/nptl.texi b/manual/nptl.texi
new file mode 100644
index 0000000..11112bd
--- /dev/null
+++ b/manual/nptl.texi
@@ -0,0 +1,33 @@
+@node Threads
+@c @node Threads, , Cryptographic Functions, Top
+@chapter Threads
+@c %MENU% Threads
+@cindex pthreads
+
+This chapter describes the the glibc pthread implementation.
+
+@menu
+* Pthread Thread-specific Data:: Pthreads support for creating and
+ managing thread-specific data
+@end menu
+
+@node Pthread Thread-specific Data
+@section Pthread Thread-specific Data
+
+@theglibc{} implements functions to allow users to create and manage
+data specific to a thread. Such data may be destroyed on thread exit,
+if a destructor is provided. The following functions are defined:
+
+@table @code
+
+@item int pthread_key_create(pthread_key_t *@var{key}, void (*@var{destructor})(void*))
+Create a thread-specific data (TSD) object for the calling thread, referenced
+by the key @var{key}. On exit of the calling thread, @var{destructor} is
+called with @var{key} as the argument.
+
+Objects declared with the C++11 @code{thread_local} keyword are destroyed
+before TSD, so they should not be used in pthread thread-specific data
+destructors or even as members of the TSD, since the latter is always passed
+as an argument to the destructor function.
+
+@end table