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: Alexandre Oliva <aoliva at redhat dot com>
- To: "Carlos O'Donell" <carlos at redhat dot com>
- Cc: codonell at redhat dot com, libc-alpha at sourceware dot org
- Date: Sat, 01 Feb 2014 04:54:46 -0200
- 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>
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?
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
--
Alexandre Oliva, freedom fighter http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/ FSF Latin America board member
Free Software Evangelist Red Hat Brazil Toolchain Engineer