This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [MTASCsft PATCH WIP6 01/33] MT-, AS- and AC-Safety docs


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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]