Add documentation for function attributes 'pure' and 'const'.

Carl suggested that cairo_pure and cairo_const are pretty opaque, even to
the developer who added them, so it is extremely important that they have
a good description so that they are used correctly and perhaps ported to
other compilers.

1 files changed, 20 insertions, 0 deletions

diff --git a/src/cairo-compiler-private.h b/src/cairo-compiler-private.h
index 9e2b4f67..5195583d 100644
--- a/src/cairo-compiler-private.h
+++ b/src/cairo-compiler-private.h
@@ -111,6 +111,26 @@
 # define CAIRO_FUNCTION_ALIAS(old, new)
 #endif
 
+/*
+ * Cairo uses the following function attributes in order to improve the
+ * generated code (effectively by manual inter-procedural analysis).
+ *
+ *   cairo_pure: The function is only allowed to read from its arguments
+ *               and global memory (i.e. following a pointer argument or
+ *               accessing a shared variable). The return value should
+ *               only depend on its arguments, and for an identical set of
+ *               arguments should return the same value.
+ *
+ *   cairo_cont: The function is only allowed to read from its arguments.
+ *               It is not allowed to access global memory. The return
+ *               value should only depend its arguments, and for an identical
+ *               set of arguments should return the same value.  This is
+ *               currently the most strict function attribute.
+ *
+ * Both these function attributes allow gcc to perform CSE and
+ * constant-folding, with cairo_const also guaranteeing that pointer contents
+ * do not change across the function call.
+ */
 #if __GNUC__ >= 3
 #define cairo_pure __attribute__((pure))
 #define cairo_const __attribute__((const))