[cairo-commit] src/cairo-compiler-private.h

[Chris Wilson]

 src/cairo-compiler-private.h |   20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

New commits:
commit 8dc3deecb8e0ca2f84d996096230f27ab4c24c18
Author: Chris Wilson <chris at chris-wilson.co.uk>
Date:   Tue Oct 14 08:17:23 2008 +0100

    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.

diff --git a/src/cairo-compiler-private.h b/src/cairo-compiler-private.h
index 9e2b4f6..5195583 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))