This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [MTASCsft PATCH WIP6 01/33] MT-, AS- and AC-Safety docs
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: Alexandre Oliva <aoliva at redhat dot com>, libc-alpha at sourceware dot org
- Date: Wed, 22 Jan 2014 22:07:41 -0500
- Subject: Re: [MTASCsft PATCH WIP6 01/33] MT-, AS- and AC-Safety docs
- Authentication-results: sourceware.org; auth=none
- References: <ortxelb5zd dot fsf at livre dot home>
On 12/07/2013 12:11 AM, Alexandre Oliva wrote:
> More comments?
This is round 2 of review.
I'm ignoring all other comments I've made to date.
This is simply a double check to see if I missed anything on the first pass.
The following is a diff of the changes to lxoliva/thread-safety-docs.
Each change should be relatively self-explanatory.
diff --git a/manual/intro.texi b/manual/intro.texi
index 4c7a3a4..45f16ae 100644
--- a/manual/intro.texi
+++ b/manual/intro.texi
@@ -212,7 +212,7 @@ concurrent calls in other threads may interfere in a destructive way.
In some cases, even expanding MT-Safe functions inline could cause
combinations to become MT-Unsafe due to reordering that this could
-enable; this is never the case of @glibcadj{} functions defined in
+enable; this is never the case for @glibcadj{} functions defined in
user-visible headers, because these are meant to be inlined, but it may
be for functions that are exported by @glibcadj{} shared libraries;
whole-program optimizations that might inline functions across library
@@ -264,7 +264,7 @@ by @theglibc{} developers.
safe to call within the safety contexts described above. Calling them
within such contexts invokes undefined behavior.
-Functions not explicitly documented as Safe in a safety context should
+Functions not explicitly documented as safe in a safety context should
be regarded as Unsafe.
@@ -318,7 +318,7 @@ sections.
Functions that are unsafe to call in certain contexts are annotated with
keywords that document their features that make them unsafe to call.
AS-Unsafe features in this section indicate the functions are never safe
-to call when asynchronous signals are enabled; AC-Unsafe ones indicate
+to call when asynchronous signals are enabled. AC-Unsafe features indicate
they are never safe to call when asynchronous cancellation is enabled.
There are no MT-Unsafe marks in this section.
@@ -457,8 +457,8 @@ refraining from calling the function altogether. The keywords that
follow refer to such features, and each of their definitions indicate
how the whole program needs to be constrained in order to remove the
safety problem indicated by the keyword. Only when all the reasons that
-make a function unsafe are observed and addressed by applying the
-documented constraints does the function become safe to call in a
+make a function unsafe are observed and addressed, by applying the
+documented constraints, does the function become safe to call in a
context.
@itemize @bullet
@@ -524,7 +524,7 @@ to callers, for example in the case of @code{obstacks}, we will annotate
functions that take such arguments with @code{race}, followed by a colon
and the argument name. We will not, however, regard such functions as
MT-Unsafe for this reason; the notion that users are expected to
-safeguard from data races objects under their control prevail.
+safeguard against data races in objects under their control prevails.
@c The above describes @mtsrace; @mtasurace is described below.
@@ -628,7 +628,7 @@ functions are also AC-Unsafe.
Besides the measures recommended to work around the MT- and AS-Safety
problem, in order to avert the cancellation problem, disabling
asynchronous cancellation @emph{and} installing a cleanup handler to
-restores the signal to the desired state and to release the mutex are
+restore the signal to the desired state and to release the mutex are
recommended.
@@ -636,11 +636,11 @@ recommended.
@cindex term
Functions marked with @code{term} as an MT-Safety issue may change the
-terminal settings in the recommended way, namely, call @code{tcgetattr},
-modify some flags, and then call @code{tcsetattr}. Because this creates
-a window in which changes made by other threads are lost, functions
-marked with @code{term} are MT-Unsafe; because this same window enables
-changes made by asynchronous signals to be lost, these functions are
+terminal settings in the recommended way, namely: call @code{tcgetattr},
+modify some flags, and then call @code{tcsetattr}; this creates
+a window in which changes made by other threads are lost. Thus, functions
+marked with @code{term} are MT-Unsafe. The same window enables
+changes made by asynchronous signals to be lost. These functions are
also AS-Unsafe, but the corresponding mark is omitted as redundant.
It is thus advisable for applications using the terminal to avoid
@@ -661,7 +661,7 @@ synchronously.
Besides the measures recommended to work around the MT- and AS-Safety
problem, in order to avert the cancellation problem, disabling
asynchronous cancellation @emph{and} installing a cleanup handler to
-restores the terminal settings to the original state and to release the
+restore the terminal settings to the original state and to release the
mutex are recommended.
--
Cheers,
Carlos.