[pypy-commit] pypy default: Add documentation to the check_*() methods in the jit tests

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r75755:ae6f25df2dfe
Date: 2015-02-07 14:44 +0100
http://bitbucket.org/pypy/pypy/changeset/ae6f25df2dfe/

Log:	Add documentation to the check_*() methods in the jit tests

diff --git a/rpython/jit/metainterp/test/support.py b/rpython/jit/metainterp/test/support.py
--- a/rpython/jit/metainterp/test/support.py
+++ b/rpython/jit/metainterp/test/support.py
@@ -162,41 +162,67 @@
 class JitMixin:
     basic = True
 
+    # Basic terminology: the JIT produces "loops" and "bridges".
+    # Bridges are always attached to failing guards.  Every loop is
+    # the "trunk" of a tree of compiled code, which is formed by first
+    # compiling a loop and then incrementally adding some number of
+    # bridges to it.  Each loop and each bridge ends with either a
+    # FINISH or a JUMP instruction (the name "loop" is not really
+    # adapted any more).  The JUMP instruction jumps to any LABEL
+    # pseudo-instruction, which can be anywhere, within the same tree
+    # or another one.
+
     def check_resops(self, expected=None, **check):
+        """Check the instructions in all loops and bridges, ignoring
+        the ones that end in FINISH.  Either pass a dictionary (then
+        the check must match exactly), or some keyword arguments (then
+        the check is only about the instructions named)."""
         get_stats().check_resops(expected=expected, **check)
 
     def check_simple_loop(self, expected=None, **check):
+        """Useful in the simplest case when we have only one loop
+        ending with a jump back to itself and possibly a few bridges.
+        Only the operations within the loop formed by that single jump
+        will be counted; the bridges are all ignored.  If several loops
+        were compiled, complains."""
         get_stats().check_simple_loop(expected=expected, **check)
 
     def check_trace_count(self, count): # was check_loop_count
-        # The number of traces compiled
+        """Check the number of loops and bridges compiled."""
         assert get_stats().compiled_count == count
 
     def check_trace_count_at_most(self, count):
+        """Check the number of loops and bridges compiled."""
         assert get_stats().compiled_count <= count
 
     def check_jitcell_token_count(self, count): # was check_tree_loop_count
+        """This should check the number of independent trees of code.
+        (xxx it is not 100% clear that the count is correct)"""
         assert len(get_stats().jitcell_token_wrefs) == count
 
     def check_target_token_count(self, count):
+        """(xxx unknown)"""
         tokens = get_stats().get_all_jitcell_tokens()
         n = sum([len(t.target_tokens) for t in tokens])
         assert n == count
 
     def check_enter_count(self, count):
+        """Check the number of times pyjitpl ran.  (Every time, it
+        should have produced either one loop or one bridge, or aborted;
+        but it is not 100% clear that this is still correct in the
+        presence of unrolling.)"""
         assert get_stats().enter_count == count
 
     def check_enter_count_at_most(self, count):
+        """Check the number of times pyjitpl ran."""
         assert get_stats().enter_count <= count
 
-    def check_jumps(self, maxcount):
-        return # FIXME
-        assert get_stats().exec_jumps <= maxcount
-
     def check_aborted_count(self, count):
+        """Check the number of times pyjitpl was aborted."""
         assert get_stats().aborted_count == count
 
     def check_aborted_count_at_least(self, count):
+        """Check the number of times pyjitpl was aborted."""
         assert get_stats().aborted_count >= count
 
     def meta_interp(self, *args, **kwds):
diff --git a/rpython/jit/metainterp/test/test_send.py b/rpython/jit/metainterp/test/test_send.py
--- a/rpython/jit/metainterp/test/test_send.py
+++ b/rpython/jit/metainterp/test/test_send.py
@@ -202,7 +202,7 @@
         # the final one.
         self.check_trace_count(1)
         self.check_resops(guard_class=1, int_add=4, int_sub=4)
-        self.check_jumps(14)
+        #self.check_jumps(14)
 
     def test_oosend_guard_failure_2(self):
         # same as above, but using prebuilt objects 'w1' and 'w2'
@@ -244,7 +244,7 @@
         assert res == f(4, 28)
         self.check_trace_count(1)
         self.check_resops(guard_class=1, int_add=4, int_sub=4)
-        self.check_jumps(14)
+        #self.check_jumps(14)
 
     def test_oosend_different_initial_class(self):
         myjitdriver = JitDriver(greens = [], reds = ['x', 'y', 'w'])