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?
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)
--
Dodji
