On Fri, 14 Nov 2014, Dodji Seketeli wrote: > Hello, > > Following the discussion at > https://gcc.gnu.org/ml/gcc-patches/2014-11/msg01755.html, > I am proposing this documentation patch to add more comments to some > gimple accessors for properties that are meant to be undefined at patch > boundaries. I haven't spotted all the properties in that case, but > perfect being the enemy of good, I thought i'd send these for now, at > least. > > OK for trunk?
Ok. Thanks, Richard. > Cheers, > > gcc/ChangeLog: > > * gimple.h (gimple_set_visited, gimple_visited_p) > (gimple_set_plf, gimple_plf, gimple_set_uid, gimple_uid): Add more > comments to these accessors. > > Signed-off-by: Dodji Seketeli <do...@redhat.com> > --- > gcc/gimple.h | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++------ > 1 file changed, 51 insertions(+), 6 deletions(-) > > diff --git a/gcc/gimple.h b/gcc/gimple.h > index c7aaa81..27bb7b6 100644 > --- a/gcc/gimple.h > +++ b/gcc/gimple.h > @@ -1585,7 +1585,17 @@ gimple_set_no_warning (gimple stmt, bool no_warning) > stmt->no_warning = (unsigned) no_warning; > } > > -/* Set the visited status on statement STMT to VISITED_P. */ > +/* Set the visited status on statement STMT to VISITED_P. > + > + Please note that this 'visited' property of the gimple statement is > + supposed to be undefined at pass boundaries. This means that a > + given pass should not assume it contains any useful value when the > + pass starts and thus can set it to any value it sees fit. > + > + You can learn more about the visited property of the gimple > + statement by reading the comments of the 'visited' data member of > + struct gimple statement_base. > + */ > > static inline void > gimple_set_visited (gimple stmt, bool visited_p) > @@ -1594,7 +1604,16 @@ gimple_set_visited (gimple stmt, bool visited_p) > } > > > -/* Return the visited status for statement STMT. */ > +/* Return the visited status for statement STMT. > + > + Please note that this 'visited' property of the gimple statement is > + supposed to be undefined at pass boundaries. This means that a > + given pass should not assume it contains any useful value when the > + pass starts and thus can set it to any value it sees fit. > + > + You can learn more about the visited property of the gimple > + statement by reading the comments of the 'visited' data member of > + struct gimple statement_base. */ > > static inline bool > gimple_visited_p (gimple stmt) > @@ -1603,7 +1622,15 @@ gimple_visited_p (gimple stmt) > } > > > -/* Set pass local flag PLF on statement STMT to VAL_P. */ > +/* Set pass local flag PLF on statement STMT to VAL_P. > + > + Please note that this PLF property of the gimple statement is > + supposed to be undefined at pass boundaries. This means that a > + given pass should not assume it contains any useful value when the > + pass starts and thus can set it to any value it sees fit. > + > + You can learn more about the PLF property by reading the comment of > + the 'plf' data member of struct gimple_statement_structure. */ > > static inline void > gimple_set_plf (gimple stmt, enum plf_mask plf, bool val_p) > @@ -1615,7 +1642,15 @@ gimple_set_plf (gimple stmt, enum plf_mask plf, bool > val_p) > } > > > -/* Return the value of pass local flag PLF on statement STMT. */ > +/* Return the value of pass local flag PLF on statement STMT. > + > + Please note that this 'plf' property of the gimple statement is > + supposed to be undefined at pass boundaries. This means that a > + given pass should not assume it contains any useful value when the > + pass starts and thus can set it to any value it sees fit. > + > + You can learn more about the plf property by reading the comment of > + the 'plf' data member of struct gimple_statement_structure. */ > > static inline unsigned int > gimple_plf (gimple stmt, enum plf_mask plf) > @@ -1624,7 +1659,12 @@ gimple_plf (gimple stmt, enum plf_mask plf) > } > > > -/* Set the UID of statement. */ > +/* Set the UID of statement. > + > + Please note that this UID property is supposed to be undefined at > + pass boundaries. This means that a given pass should not assume it > + contains any useful value when the pass starts and thus can set it > + to any value it sees fit. */ > > static inline void > gimple_set_uid (gimple g, unsigned uid) > @@ -1633,7 +1673,12 @@ gimple_set_uid (gimple g, unsigned uid) > } > > > -/* Return the UID of statement. */ > +/* Return the UID of statement. > + > + Please note that this UID property is supposed to be undefined at > + pass boundaries. This means that a given pass should not assume it > + contains any useful value when the pass starts and thus can set it > + to any value it sees fit. */ > > static inline unsigned > gimple_uid (const_gimple g) > -- Richard Biener <rguent...@suse.de> SUSE LINUX GmbH, GF: Jeff Hawn, Jennifer Guild, Felix Imendoerffer, HRB 21284 (AG Nuernberg) Maxfeldstrasse 5, 90409 Nuernberg, Germany
