This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [MTASCsft PATCH 35/??] MT-, AS- and AC-Safety docs: manual/threads.texi
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Alexandre Oliva <aoliva at redhat dot com>
- Cc: codonell at redhat dot com, libc-alpha at sourceware dot org
- Date: Mon, 03 Feb 2014 09:17:03 -0500
- Subject: Re: [MTASCsft PATCH 35/??] MT-, AS- and AC-Safety docs: manual/threads.texi
- Authentication-results: sourceware.org; auth=none
- References: <ortxelb5zd dot fsf at livre dot home> <or4n4uoncj dot fsf at livre dot home> <orr47seo2e dot fsf_-_ at livre dot home> <52EC5BDE dot 1090006 at redhat dot com> <orioszldhj dot fsf at livre dot home> <52EC8763 dot 5030106 at redhat dot com> <orlhxvjpah dot fsf at livre dot home>
On 02/01/2014 01:54 AM, Alexandre Oliva wrote:
> On Feb 1, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:
>
>> Please change them to deftypefun and review them?
>
>> Feel free to make it a follow on patch to reduce your set of
>> outstanding patches.
>
> Here it is. Ok?
OK to checkin.
I feel like I already reviewed this, but it was in my inbox
so I reviewed it :-)
> Use @deftypefun for key/specific fns, and add safety notes
>
> From: Alexandre Oliva <aoliva@redhat.com>
>
> for ChangeLog
>
> * manual/threads.texi (pthread_key_create, pthread_key_delete,
> pthread_getspecific, pthread_setspecific): Format with
> @deftypefun, and add @safety note.
> * manual/signal.texi: Move comments that analyze the above
> functions to their home place.
> ---
> manual/signal.texi | 15 +++------------
> manual/threads.texi | 36 ++++++++++++++++++++++++++++--------
> 2 files changed, 31 insertions(+), 20 deletions(-)
>
> diff --git a/manual/signal.texi b/manual/signal.texi
> index 1a32391..f0e57dd 100644
> --- a/manual/signal.texi
> +++ b/manual/signal.texi
> @@ -894,22 +894,13 @@ may come from a signal handler in the same process.
> @c uses a static buffer if tsd key creation fails
> @c [once] init
> @c libc_key_create ok
> -@c pthread_key_create ok
> -@c KEY_UNUSED ok
> -@c KEY_USABLE ok
> +@c pthread_key_create dup ok
> @c getbuffer @asucorrupt @ascuheap @acsmem
> @c libc_getspecific ok
> -@c pthread_getspecific ok
> +@c pthread_getspecific dup ok
> @c malloc dup @ascuheap @acsmem
> @c libc_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem
> -@c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem
> -@c a level2 block may be allocated by a signal handler after
> -@c another call already made a decision to allocate it, thus losing
> -@c the allocated value. the seq number is updated before the
> -@c value, which might cause an earlier-generation value to seem
> -@c current if setspecific is cancelled or interrupted by a signal
> -@c KEY_UNUSED ok
> -@c calloc dup @ascuheap @acsmem
> +@c pthread_setspecific dup @asucorrupt @ascuheap @acucorrupt @acsmem
> @c snprintf dup @mtslocale @ascuheap @acsmem
> @c _ @ascuintl
> This function returns a pointer to a statically-allocated string
> diff --git a/manual/threads.texi b/manual/threads.texi
> index 7cf5be2..e088b26 100644
> --- a/manual/threads.texi
> +++ b/manual/threads.texi
> @@ -20,9 +20,11 @@ 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*))
> +@deftypefun int pthread_key_create (pthread_key_t *@var{key}, void (*@var{destructor})(void*))
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c pthread_key_create ok
> +@c KEY_UNUSED ok
> +@c KEY_USABLE ok
> Create a thread-specific data key for the calling thread, referenced by
> @var{key}.
>
> @@ -30,21 +32,39 @@ 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.
> +@end deftypefun
>
> -@c FIXME: use @deftypefun for these.
> -@item int pthread_key_delete (pthread_key_t @var{key})
> +@deftypefun int pthread_key_delete (pthread_key_t @var{key})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c pthread_key_delete ok
> +@c This uses atomic compare and exchange to increment the seq number
> +@c after testing it's not a KEY_UNUSED seq number.
> +@c KEY_UNUSED dup ok
> 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.
> +@end deftypefun
>
> -@item void *pthread_getspecific (pthread_key_t @var{key})
> +@deftypefun void *pthread_getspecific (pthread_key_t @var{key})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c pthread_getspecific ok
> Return the thread-specific data associated with @var{key} in the calling
> thread.
> +@end deftypefun
>
> -@item int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
> +@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
> +@c pthread_setspecific @asucorrupt @ascuheap @acucorrupt @acsmem
> +@c a level2 block may be allocated by a signal handler after
> +@c another call already made a decision to allocate it, thus losing
> +@c the allocated value. the seq number is updated before the
> +@c value, which might cause an earlier-generation value to seem
> +@c current if setspecific is cancelled or interrupted by a signal
> +@c KEY_UNUSED ok
> +@c calloc dup @ascuheap @acsmem
> Associate the thread-specific @var{value} with @var{key} in the calling thread.
> +@end deftypefun
>
> -@end table
>
> @node Non-POSIX Extensions
> @section Non-POSIX Extensions
>
>
Cheers,
Carlos.