This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] Create nptl manual node and document thread_local limitation
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Siddhesh Poyarekar <siddhesh at redhat dot com>
- Cc: libc-alpha at sourceware dot org
- Date: Wed, 20 Feb 2013 11:03:48 -0500
- Subject: Re: [PATCH] Create nptl manual node and document thread_local limitation
- References: <20130220115335.GC26842@spoyarek.pnq.redhat.com>
On 02/20/2013 06:53 AM, Siddhesh Poyarekar wrote:
> 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
s/Threads/POSIX Threads/g
> @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.
s/the glibc/the @glibcadj{}/g
s/pthread/POSIX thread/g
We should use "thread", "threads", "POSIX thread", "POSIX threads"
but not "pthread" or "pthreads."
> +
> +@menu
> +* Pthread Thread-specific Data:: Pthreads support for creating and
s/Pthread//g
s/s support/Support/g
> + managing thread-specific data
> +@end menu
> +
> +@node Pthread Thread-specific Data
s/Pthread//g
> +@section Pthread Thread-specific Data
s/Pthread//g
> +
> +@theglibc{} implements functions to allow users to create and manage
> +data specific to a thread. Such data may be destroyed on thread exit,
s/on thread/at thread/g
> +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
s/(TSD)//g
Please don't use an acronym. Repeat the phrase as required or use a macro to cut
down on typing.
> +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
Please include empty entries for:
pthread_key_delete
pthread_getspecific
pthread_setspecific
They should say something like "Not currently documented."
This completes the section on thread-specific data.
OK with those changes.
Cheers,
Carlos.