print warning for unclaimed TCO jump instances (when they get GC'd)

Author: Technologicat

README.md

@@ -248,6 +248,10 @@ Here `jump` is **a noun, not a verb**. The `jump(f, ...)` part just evaluates to
 
 The final result is just returned normally. Returning a normal value (anything that is not a ``jump`` instance) to a trampoline shuts down that trampoline, and returns the given value from the initial call (to a ``@trampolined`` function) that originally started that trampoline.
 
+Trying to ``jump(...)`` without the ``return`` will **usually** print a warning. This is implemented by checking a flag in the ``__del__`` method; any correctly used jump instance should have been claimed by a trampoline at some point in its lifetime.
+
+If you prefer the syntax without the explicit ``return``, see [`tco_exc.py`](unpythonic/tco_exc.py). **Since this is pre-1.0**, the default implementation (and the import in [`fploop.py`](unpythonic/fploop.py)) is still subject to change.
+
 *Tail recursion in a lambda*:
 
 ```python

unpythonic/__init__.py

@@ -34,5 +34,5 @@
 from .misc import *
 from .tco import *
 
-__version__ = '0.4.2'
+__version__ = '0.4.3'
 

unpythonic/tco.py

@@ -129,6 +129,7 @@ def baz():
 __all__ = ["SELF", "jump", "trampolined"]
 
 from functools import wraps
+from sys import stderr
 
 from unpythonic.misc import call
 
@@ -170,6 +171,66 @@ def __init__(self, target, args, kwargs):
         self.target = target._entrypoint if hasattr(target, "_entrypoint") else target
         self.args = args
         self.kwargs = kwargs
+        self._claimed = False  # set when the instance is caught by a trampoline
+
+    def __repr__(self):
+        return "<_jump at 0x{:x}: target={}, args={}, kwargs={}".format(id(self),
+                                                                        self.target,
+                                                                        self.args,
+                                                                        self.kwargs)
+
+    def __del__(self):
+        """Warn about bugs in client code.
+
+        Since it's ``__del__``, we can't raise any exceptions - which includes
+        things such as ``AssertionError`` and ``SystemExit``. So we print a
+        warning.
+
+        **CAUTION**:
+
+            This warning mechanism should help find bugs, but it is not 100% foolproof.
+            Since ``__del__`` is managed by Python's GC, some object instances may
+            not get their ``__del__`` called when the Python interpreter itself exits
+            (if those instances are still alive at that time).
+
+        **Typical causes**:
+
+        *Missing "return"*::
+
+            @trampolined
+            def foo():
+                jump(bar, 42)
+
+        The jump instance was never actually passed to the trampoline; it was
+        just created and discarded. The trampoline got the ``None`` from the
+        implicit ``return None`` at the end of the function.
+
+        (See ``tco_exc.py`` if you prefer this syntax, without a ``return``.)
+
+        *No trampoline*::
+
+            def foo():
+                return jump(bar, 42)
+
+        Here ``foo`` is not trampolined.
+
+        We **have** a trampoline when the function that returns the jump
+        instance is itself ``@trampolined``, or is running in a trampoline
+        implicitly (due to having been entered via a tail call).
+
+        *Trampoline at the wrong level*::
+
+            @trampolined
+            def foo():
+                def bar():
+                    return jump(qux, 23)
+                bar()  # normal call, no TCO
+
+        Here ``bar`` has no trampoline; only ``foo`` does. **Only** a ``@trampolined``
+        function, or a function entered via a tail call, may return a jump.
+        """
+        if not self._claimed:
+            print("WARNING: unclaimed {}".format(repr(self)), file=stderr)
 
 # We want @wraps to preserve docstrings, so the decorator must be a function, not a class.
 # https://stackoverflow.com/questions/6394511/python-functools-wraps-equivalent-for-classes
@@ -191,6 +252,7 @@ def decorated(*args, **kwargs):
                     f = v.target
                 args = v.args
                 kwargs = v.kwargs
+                v._claimed = True
             else:  # final result, exit trampoline
                 return v
     # fortunately functions in Python are just objects; stash for jump constructor
@@ -258,6 +320,18 @@ def baz():
 
     print("All tests PASSED")
 
+    print("*** These two error cases SHOULD PRINT A WARNING:", file=stderr)
+    print("** No surrounding trampoline:", file=stderr)
+    def bar2():
+        pass
+    def foo2():
+        return jump(bar2)
+    foo2()
+    print("** Missing 'return' in 'return jump':", file=stderr)
+    def foo3():
+        jump(bar2)
+    foo3()
+
     # loop performance?
     n = 100000
     import time

unpythonic/tco_exc.py

@@ -61,10 +61,19 @@ def __init__(self, target, args, kwargs):
         self.tkwargs = kwargs
 
         # Error message when uncaught
+        # (This can still be caught by the wrong trampoline, if an inner trampoline
+        #  has been forgotten when nesting TCO chains - there's nothing we can do
+        #  about that.)
         self.args = ("No trampoline, attempted to jump to '{}', args {}, kwargs {}".format(target,
                                                                                            args,
                                                                                            kwargs),)
 
+    def __repr__(self):
+        return "<TrampolinedJump at 0x{:x}: target={}, args={}, kwargs={}".format(id(self),
+                                                                                  self.target,
+                                                                                  self.targs,
+                                                                                  self.tkwargs)
+
 def trampolined(function):
     """Decorator to make a function trampolined.