* lib/attribute.h: Update [[unsequenced]]/[[reproducible]]
comments to match m4/gnulib-common.m4.
---
lib/attribute.h | 80 +++++++++++++++++++++++++++----------------------
1 file changed, 45 insertions(+), 35 deletions(-)
diff --git a/lib/attribute.h b/lib/attribute.h
index f24f5b18f1..60ec5391b6 100644
--- a/lib/attribute.h
+++ b/lib/attribute.h
@@ -240,29 +240,36 @@
/* Applies to: functions. */
#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
-/* It is OK for a compiler to move calls to the function and to omit
- calls to the function if another call has the same arguments or the
- result is not used.
- This attribute is safe for a function that neither depends on
- nor affects state, and always returns exactly once -
+/* It is OK for a compiler to move a call, or omit a duplicate call
+ and reuse a cached return value, even if the state changes between calls.
+ It is also OK to omit a call if the result is not used.
+ This attribute is safe if the function does not change observable state,
+ returns a value determined solely by its arguments' values
+ without examining state, and always returns exactly once -
e.g., does not raise an exception, call longjmp, or loop forever.
- (This attribute is stricter than ATTRIBUTE_PURE because the
- function cannot observe state. It is stricter than UNSEQUENCED
- because the function must return exactly once and cannot depend on
- state addressed by its arguments.) */
+ (This attribute is stricter than _GL_ATTRIBUTE_PURE because the
+ function cannot observe state. Unlike _GL_ATTRIBUTE_UNSEQUENCED
+ the function must return exactly once and cannot access state
+ addressed by its pointer arguments or that happens to have the same
+ value for all calls to the function, but the function is allowed to
+ return a pointer to storage that can be modified later. */
/* Applies to: functions. */
#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
-/* It is OK for a compiler to move calls to the function and to omit duplicate
- calls to the function with the same arguments, so long as the state
- addressed by its arguments is the same.
+/* It is OK for a compiler to move a call, or omit a duplicate call
+ and reuse a cached value returned either directly or indirectly via
+ a pointer, if the state addressed by its pointer arguments is the same;
+ however, pointer arguments cannot alias.
This attribute is safe for a function that is effectless, idempotent,
stateless, and independent; see ISO C 23 § 6.7.13.8 for a definition of
these terms.
- (This attribute is stricter than REPRODUCIBLE because the function
- must be stateless and independent. It is looser than ATTRIBUTE_CONST
- because the function need not return exactly once and can depend
- on state addressed by its arguments.)
+ (This attribute is stricter than _GL_ATTRIBUTE_REPRODUCIBLE because
+ the function must be stateless and independent. Unlike
+ _GL_ATTRIBUTE_CONST the function need not return exactly once, and
+ can depend on state accessed via its pointer arguments or that
+ happens to have the same value for all calls to the function, but
+ the function cannot return a pointer to storage whose contents
+ change later.)
See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
<https://stackoverflow.com/questions/76847905/>.
ATTENTION! Efforts are underway to change the meaning of this attribute.
@@ -270,28 +277,31 @@
/* Applies to: functions, pointer to functions, function type. */
#define UNSEQUENCED _GL_ATTRIBUTE_UNSEQUENCED
-/* It is OK for a compiler to move calls to the function and to omit
- calls to the function if another call has the same arguments or the
- result is not used, and if observable state is the same.
- This attribute is safe for a function that does not affect observable state
- and always returns exactly once.
- (This attribute is looser than ATTRIBUTE_CONST because the function
- can depend on observable state. It is stricter than REPRODUCIBLE
- because the function must return exactly once and cannot affect
- state addressed by its arguments.) */
+/* It is OK for a compiler to move a call, or omit a duplicate call
+ and reuse a cached return value, if observable state is the same.
+ It is also OK to omit a call if the return value is not used.
+ This attribute is safe if the function does not change observable state,
+ returns a value determined solely by its arguments's values
+ together with observable state, and always returns exactly once.
+ (This attribute is looser than _GL_ATTRIBUTE_CONST because the function
+ can depend on observable state.
+ Unlike _GL_ATTRIBUTE_REPRODUCIBLE the function must return exactly
+ once and cannot change state addressed by its arguments, but the
+ function can return a pointer to storage whose contents change later.) */
/* Applies to: functions. */
#define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
-/* It is OK for a compiler to move calls to the function and to omit duplicate
- calls to the function with the same arguments, so long as the state
- addressed by its arguments is the same and is updated in time for
- the rest of the program.
- This attribute is safe for a function that is effectless and idempotent; see
- ISO C 23 § 6.7.13.8 for a definition of these terms.
- (This attribute is looser than UNSEQUENCED because the function need
- not be stateless and idempotent. It is looser than ATTRIBUTE_PURE
- because the function need not return exactly once and can affect
- state addressed by its arguments.)
+/* It is OK for a compiler to move a call, or omit a duplicate call
+ and reuse a cached value returned either directly or indirectly via
+ a pointer, if other observable state is the same;
+ however, pointer arguments cannot alias.
+ This attribute is safe for a function that is effectless and idempotent;
+ see ISO C 23 § 6.7.13.8 for a definition of these terms.
+ (This attribute is looser than _GL_ATTRIBUTE_UNSEQUENCED because
+ the function need not be stateless or independent.
+ Unlike _GL_ATTRIBUTE_PURE the function need not return exactly once
+ and can change state addressed by its pointer arguments, but the
+ function cannot return a pointer to storage whose contents change later.)
See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
<https://stackoverflow.com/questions/76847905/>.
ATTENTION! Efforts are underway to change the meaning of this attribute.
--
2.51.0
