Re: [RFC PATCH glibc] pthread_setspecific: Provide signal-safety across keys

[Mathieu Desnoyers <mathieu dot desnoyers at efficios dot com>]

----- On Oct 17, 2017, at 6:50 PM, Joseph Myers joseph@codesourcery.com wrote:

> On Tue, 17 Oct 2017, Mathieu Desnoyers wrote:
> 
>> Can you provide a general hint on which repo and which documentation file
>> I should update ?
> 
> That same file in the manual.  But rather than just editing comments
> referring to details of the implementation, you need to write non-comment
> text explaining at the user API level, without reference to implementation
> internals, what API guarantees are provided in this regard.  The text
> should be sufficient for users to understand what uses they can make of
> the API without needing to refer to implementation sources.

Gotcha. So I guess we need to update pthread_getspecific too
to document its async-signal safetyness, to make all this
somewhat useful.

How about the following ?

@deftypefun void *pthread_getspecific (pthread_key_t @var{key})
@standards{POSIX, pthread.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c pthread_getspecific ok
Return the thread-specific data associated with @var{key} in the calling
thread.
As a non-POSIX extension, pthread_getspecific is async-signal safe.
@end deftypefun

@deftypefun int pthread_setspecific (pthread_key_t @var{key}, const void *@var{value})
@standards{POSIX, pthread.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @acsmem{}}}
@c pthread_setspecific @asucorrupt @acucorrupt @acsmem
@c   the seq number is updated before the value, which might cause
@c   an earlier-generation value to seem current if setspecific is
@c   cancelled or interrupted by a signal
@c  KEY_UNUSED ok
@c  dup @acsmem
Associate the thread-specific @var{value} with @var{key} in the calling thread.
As a non-POSIX extension, pthread_setspecific is async-signal safe for
concurrent invocations against different @var{key}, but not async-signal
safe for concurrent invocations against the same @var{key}.
@end deftypefun

Thanks,

Mathieu


> 
> --
> Joseph S. Myers
> joseph@codesourcery.com

-- 
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com