This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] Create nptl manual node and document thread_local limitation


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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]