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, 13 Mar 2013 17:10:07 -0400
- Subject: Re: [PATCH] Create nptl manual node and document thread_local limitation
- References: <20130220115335.GC26842@spoyarek.pnq.redhat.com> <5124F3E4.7030909@redhat.com> <20130221050630.GH26842@spoyarek.pnq.redhat.com> <20130313125858.GL22471@spoyarek.pnq.redhat.com>
On 03/13/2013 08:58 AM, Siddhesh Poyarekar wrote:
> Ping!
>
> On Thu, Feb 21, 2013 at 10:36:30AM +0530, Siddhesh Poyarekar wrote:
>> On Wed, Feb 20, 2013 at 11:03:48AM -0500, Carlos O'Donell wrote:
>>> 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.
>>>
>>
>> I wrote up one-line descriptions for them instead, so here's the
>> updated patch.
>>
>> Siddhesh
ChangeLog?
>> 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..1db9c18 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, 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
>> index 0000000..c727870
>> --- /dev/null
>> +++ b/manual/nptl.texi
>> @@ -0,0 +1,46 @@
>> +@node POSIX Threads
>> +@c @node POSIX Threads, , Cryptographic Functions, Top
>> +@chapter POSIX Threads
>> +@c %MENU% POSIX Threads
>> +@cindex pthreads
Is the @cindex visible anywhere? We want to avoid the colloquial `pthreads'
appearing in text.
>> +
>> +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 object for the calling thread, referenced by the
I would adjust this to say it creates a "thread-specific data key".
I don't know that you need to be as verbose as "by the key @var{key}".
How about:
"Create a thread-specific data key for the calling thread, referenced by @var{key}."
>> +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 thread-specific data, so they should not be used in pthread
s/pthread//g
>> +thread-specific data destructors or even as members of the thread-specific
>> +data, since the latter is always passed as an argument to the destructor
s/always//g
>> +function.
>> +
>> +@item int pthread_key_delete (pthread_key_t @var{key})
>> +Destroy the thread-specific data referenced by @var{key} in the calling
I would say "Destory the thread-specific data @var{key} in the calling thread."
>> +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 referenced by @var{key} in the calling thread.
I'd use "associated" rather than "referenced" since it's a mapping.
"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})
>> +Set @var{value} as the thread-specific data to be referred by @var{key} in the
>> +calling thread.
"Associate the thread-specific @var{value} with @var{key} in the calling thread."
>> +@end table
OK with those changes and a ChangeLog.
Cheers,
Carlos.