[pypy-commit] pypy stmgc-c7-rewindjmp: Document the kind of trace produced by jit_stm_xxx(), before refactoring it.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: stmgc-c7-rewindjmp
Changeset: r72845:35c9220c71f4
Date: 2014-08-17 17:38 +0200
http://bitbucket.org/pypy/pypy/changeset/35c9220c71f4/

Log:	Document the kind of trace produced by jit_stm_xxx(), before
	refactoring it.

diff --git a/rpython/rlib/rstm.py b/rpython/rlib/rstm.py
--- a/rpython/rlib/rstm.py
+++ b/rpython/rlib/rstm.py
@@ -53,6 +53,26 @@
         if llop.stm_should_break_transaction(lltype.Bool):
             llop.stm_transaction_break(lltype.Void)
 
+# Typical usage of the following two functions:
+#
+# just after jit_merge_point:
+#         if rstm.jit_stm_should_break_transaction(False):
+#             rstm.jit_stm_transaction_break_point()
+#
+# just before can_enter_jit:
+#         if rstm.jit_stm_should_break_transaction(True):
+#             rstm.jit_stm_transaction_break_point()
+#
+# resulting JIT trace (common case):
+#      ...
+#      call_release_gil(...)
+#      stm_transaction_break(0)     # in-line, because we expect "inevitable"
+#      guard_not_forced()
+#      ...
+#      i1 = stm_should_break_transaction()
+#      guard_false(i1)              # out-of-line, because rarely needed
+#      jump()
+#
 def jit_stm_transaction_break_point():
     # XXX REFACTOR AWAY
     if we_are_translated():