Re: [MTASCsft PATCH 35/??] MT-, AS- and AC-Safety docs: manual/threads.texi

["Carlos O'Donell" <carlos at redhat dot com>]

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.