Add nptl manual chapter

This adds the base chapter for POSIX threads and also documentation
for thread-specific data, along with a note on its interaction with
C++11 thread_local variables.

diff --git a/ChangeLog b/ChangeLog
index fced6c0..8fb2ba7 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2013-03-14  Siddhesh Poyarekar  <siddhesh@redhat.com>
 
+       * manual/Makefile (chapters): Add nptl.
+       * manual/debug.texi (Debugging Support): Add link to Threads
+       chapter.
+       * manual/nptl.texi: New file.
+
        * sysdeps/unix/sysv/linux/times.c (__times): Fix formatting.
 
 2013-03-14  Petr Baudis  <pasky@ucw.cz>

diff --git a/manual/Makefile b/manual/Makefile
index c1a304c..10314a9 100644 (file)
--- 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..1db9c18 100644 (file)
--- 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, POSIX 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 (file)
index 0000000..f1d8f08
--- /dev/null
+++ b/manual/nptl.texi
@@ -0,0 +1,44 @@
+@node POSIX Threads
+@c @node POSIX Threads, , Cryptographic Functions, Top
+@chapter POSIX Threads
+@c %MENU% POSIX Threads
+@cindex threads
+
+This chapter describes the @glibcadj{} POSIX Thread implementation.
+
+@menu
+* Thread-specific Data::          Support for creating and
+                                 managing thread-specific data
+@end menu
+
+@node Thread-specific Data
+@section Thread-specific Data
+
+The @glibcadj{} implements functions to allow users to create and manage
+data specific to a thread.  Such data may be destroyed at 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 key for the calling thread, referenced by
+@var{key}.
+
+Objects declared with the C++11 @code{thread_local} keyword are destroyed
+before thread-specific data, so they should not be used in thread-specific
+data destructors or even as members of the thread-specific data, since the
+latter is passed as an argument to the destructor function.
+
+@item int pthread_key_delete (pthread_key_t @var{key})
+Destroy the thread-specific data @var{key} in the calling thread.  The
+destructor for the thread-specific data is not called during destruction, nor
+is it called during thread exit.
+
+@item void *pthread_getspecific (pthread_key_t @var{key})
+Return the thread-specific data associated with @var{key} in the calling
+thread.
+
+@item int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
+Associate the thread-specific @var{value} with @var{key} in the calling thread.
+
+@end table