[pypy-commit] pypy jit_hint_docs: Add more detail to @jit.elidable and @jit.promote.

[vext01]

Author: Edd Barrett <vext01 at gmail.com>
Branch: jit_hint_docs
Changeset: r76961:8d151b2df127
Date: 2015-05-01 15:36 +0100
http://bitbucket.org/pypy/pypy/changeset/8d151b2df127/

Log:	Add more detail to @jit.elidable and @jit.promote.

diff --git a/rpython/rlib/jit.py b/rpython/rlib/jit.py
--- a/rpython/rlib/jit.py
+++ b/rpython/rlib/jit.py
@@ -34,6 +34,26 @@
     side effect, but those side effects are idempotent (ie caching).
     If a particular call to this function ends up raising an exception, then it
     is handled like a normal function call (this decorator is ignored).
+
+    Note also that this optimisation will only take effect if the arguments
+    to the function are "provably constant". By this we mean each argument
+    is either:
+
+      1) literally constant in the RPython source
+      2) easily shown to be constant by the tracer
+      3) a promoted variable (see @jit.promote)
+
+    Examples of condition 2:
+
+      * i1 = int_eq(i0, 0), guard_true(i1)
+      * i1 = getfield_pc_pure(<constant>, "immutable_field")
+
+    In both cases, the tracer will deduce that i1 is constant.
+
+    Failing the above conditions, the function is not traced into (as if the
+    function were decorated with @jit.dont_look_inside). Generally speaking,
+    it is a bad idea to liberally sprinkle @jit.elidable without a concrete
+    need.
     """
     if DEBUG_ELIDABLE_FUNCTIONS:
         cache = {}
@@ -78,6 +98,25 @@
 
 @specialize.argtype(0)
 def promote(x):
+    """
+    Promotes a variable in a trace to a constant.
+
+    When a variable is promoted, a guard is inserted that assumes the value
+    of the variable is constant. In other words, the value of the variable
+    is checked to be the same as it was at trace collection time.  Once the
+    variable is assumed constant, more aggressive constant folding may be
+    possible.
+
+    If however, the guard fails frequently, a bridge will be generated
+    this time assuming the constancy of the variable under its new value.
+    This optimisation should be used carefully, as in extreme cases, where
+    the promoted variable is not very constant at all, code explosion can
+    occur. In turn this leads to poor performance.
+
+    Overpromotion is characterised by a cascade of bridges branching from
+    very similar guard_value opcodes, each guarding the same variable under
+    a different value.
+    """
     return hint(x, promote=True)
 
 def promote_string(x):