New let stable; supercedes old simplify-on-state

- New grammar for `let stable`
- Track bindings and resimplify if they become stable
- Undo simplification if value later changes
- Can use this to individually target stable state values to simplify on 
instead of tracking whole state change generations
- Implements #80

Author: jonathanhogg

atom/language-flitter/grammars/flitter.cson

@@ -79,7 +79,7 @@ patterns: [
                 name: "keyword.control.flow.flitter"
     }
     {
-        match: "\\b(if|elif|else|let|where)\\b"
+        match: "\\b(if|elif|else|let|stable|where)\\b"
         name: "keyword.control.flow.flitter"
     }
     {

docs/language.md

@@ -706,6 +706,32 @@ let x' = x + 1
 All identifiers may contain any number of single quote characters at the end.
 :::
 
+### Stable let
+
+The `let` keyword may be followed by the optional `stable` keyword to
+indicate bindings that are expected to be unchanging for long periods of time.
+When a stable let binding evaluates to the same value as it did in the last
+frame, the engine will re-simplify the program with the assumption that this
+value is now static. A run-time check will also be compiled in that verifies
+the value remains static. In the event that this check fails, execution will
+be abandoned and restarted with the original program.
+
+For example:
+
+```flitter
+let static SEED=time//30
+           THINGS_COUNT=$:things_knob
+```
+
+In cases where a value controls large portions of the program but changes
+infrequently, use of `let stable` can result in significant speed-ups. As the
+evaluated binding is always compared to the previous value, it is fine for the
+value to change continuously for short periods – for example, while turning a
+knob – as long as it then settles to a value that remains stable for a long
+period. Avoid using `let stable` for values that are stable for only short
+periods of time as the overhead of continuously re-simplifying the program
+may result in worse performance instead of better.
+
 ## Where
 
 There is also an inline version of `let` known as `where`. This allows names to

src/flitter/engine/__main__.py

@@ -50,7 +50,6 @@ def main():
     parser.add_argument('--state', type=str, help="State save/restore file")
     parser.add_argument('--resetonswitch', action='store_true', default=False, help="Reset state when switching pages")
     parser.add_argument('--nosimplify', action='store_true', default=False, help="Disable the language simplifier")
-    parser.add_argument('--simplifystate', type=convert_timecode_to_float, default=10, help="Simplify on state after stable period")
     parser.add_argument('--lockstep', action='store_true', default=False, help="Run clock in non-realtime mode")
     parser.add_argument('--define', '-D', action='append', default=[], type=keyvalue, dest='defines', help="Define name for evaluation")
     parser.add_argument('--vmstats', action='store_true', default=False, help="Report VM statistics")
@@ -69,7 +68,7 @@ def main():
             return os.execlp(sys.argv[0], *sys.argv)
     logger.info("Flitter version {}", __version__)
     controller = EngineController(target_fps=args.fps, screen=args.screen, fullscreen=args.fullscreen, vsync=args.vsync,
-                                  state_file=args.state, reset_on_switch=args.resetonswitch, state_simplify_wait=args.simplifystate,
+                                  state_file=args.state, reset_on_switch=args.resetonswitch,
                                   realtime=not args.lockstep, defined_names=dict(args.defines), vm_stats=args.vmstats,
                                   run_time=args.runtime, offscreen=args.offscreen, disable_simplifier=args.nosimplify,
                                   opengl_es=args.opengles, model_cache_time=args.modelcache)

src/flitter/engine/control.py

@@ -13,7 +13,7 @@
 from .. import setproctitle
 from ..cache import SharedCache
 from ..clock import BeatCounter, system_clock
-from ..language.vm import log_vm_stats
+from ..language.vm import log_vm_stats, ProgramInvalid
 from ..model import Vector, StateDict, Context, null, numbers_cache_counts, empty_numbers_cache
 from ..plugins import get_plugin
 from ..render.window.models import Model
@@ -24,7 +24,7 @@ class EngineController:
     MINIMUM_GC_INTERVAL = 10
 
     def __init__(self, target_fps=60, screen=0, fullscreen=False, vsync=False, state_file=None,
-                 reset_on_switch=False, state_simplify_wait=0, realtime=True, defined_names=None, vm_stats=False,
+                 reset_on_switch=False, realtime=True, defined_names=None, vm_stats=False,
                  run_time=None, offscreen=False, disable_simplifier=False, opengl_es=False, model_cache_time=300):
         self.default_fps = target_fps
         self.target_fps = target_fps
@@ -37,7 +37,6 @@ def __init__(self, target_fps=60, screen=0, fullscreen=False, vsync=False, state
         self.model_cache_time = model_cache_time
         self.reset_on_switch = reset_on_switch
         self.disable_simplifier = disable_simplifier
-        self.state_simplify_wait = 0 if self.disable_simplifier else state_simplify_wait / 2
         if defined_names:
             self.defined_names = {key: Vector.coerce(value) for key, value in defined_names.items()}
             logger.trace("Defined names: {!r}", self.defined_names)
@@ -60,10 +59,6 @@ def __init__(self, target_fps=60, screen=0, fullscreen=False, vsync=False, state
             self.global_state = {}
         self.global_state_dirty = False
         self.state = None
-        self.state_timestamp = None
-        self.state_generation0 = None
-        self.state_generation1 = None
-        self.state_generation2 = None
         self.renderers = {}
         self.counter = BeatCounter()
         self.pages = []
@@ -89,10 +84,6 @@ def switch_to_page(self, page_number):
                 self.state.clear_changed()
             path, state = self.pages[page_number]
             self.state = state
-            self.state_timestamp = system_clock()
-            self.state_generation0 = set()
-            self.state_generation1 = set()
-            self.state_generation2 = set()
             self.current_path = path
             self.current_page = page_number
             SharedCache.set_root(self.current_path)
@@ -178,7 +169,8 @@ async def run(self):
             gc_pending = False
             last_gc = None
             run_program = current_program = errors = logs = None
-            simplify_state_time = frame_time + self.state_simplify_wait
+            stables = set()
+            stable_cache = {}
             static = dict(self.defined_names)
             static.update({'realtime': self.realtime, 'screen': self.screen, 'fullscreen': self.fullscreen,
                            'vsync': self.vsync, 'offscreen': self.offscreen, 'opengl_es': self.opengl_es, 'run_time': self.run_time})
@@ -203,19 +195,20 @@ async def run(self):
                     run_program = current_program = program
                     self.handle_pragmas(program.pragmas, frame_time)
                     errors = logs = None
-                    self.state_generation0 ^= self.state_generation1
-                    self.state_generation1 = self.state_generation2
-                    self.state_generation2 = set()
-                    simplify_state_time = frame_time + self.state_simplify_wait
 
                 now = system_clock()
                 housekeeping += now
                 execution -= now
 
                 if run_program is not None:
                     context = Context(names={key: Vector.coerce(value) for key, value in dynamic.items()},
-                                      state=self.state, references=self._references)
-                    run_program.run(context, record_stats=self.vm_stats)
+                                      state=self.state, references=self._references, stables=stables, stable_cache=stable_cache)
+                    try:
+                        run_program.run(context, record_stats=self.vm_stats)
+                    except ProgramInvalid:
+                        logger.debug("Simplified program invalidated due to change of stable value")
+                        run_program = current_program
+                        run_program.run(context, record_stats=self.vm_stats)
                 else:
                     context = Context()
 
@@ -240,50 +233,21 @@ async def run(self):
 
                 self.state['_counter'] = self.counter.tempo, self.counter.quantum, self.counter.start
 
-                if self.state.changed:
-                    if self.state_simplify_wait:
-                        changed_keys = self.state.changed_keys - self.state_generation0
-                        self.state_generation0 ^= changed_keys
-                        self.state_generation0 &= self.state.keys()
-                        if changed_keys:
-                            generation1to0 = self.state_generation1 & changed_keys
-                            changed_keys -= generation1to0
-                            self.state_generation1 -= generation1to0
-                            generation2to0 = self.state_generation2 & changed_keys
-                            if generation2to0:
-                                if run_program is not current_program:
-                                    run_program = current_program
-                                    logger.debug("Undo simplification on state; original program with {} instructions", len(run_program))
-                                self.state_generation1 ^= self.state_generation2 - generation2to0
-                                self.state_generation2 = set()
-                                simplify_state_time = frame_time + self.state_simplify_wait
-                    self.global_state_dirty = True
-                    self.state_timestamp = frame_time
-                    self.state.clear_changed()
-
-                if self.state_simplify_wait and frame_time > simplify_state_time:
-                    if current_program is not None and self.state_generation1:
-                        if self.state_generation1:
-                            self.state_generation2 ^= self.state_generation1
-                            simplify_state = self.state.with_keys(self.state_generation2)
-                            simplify_time = -system_clock()
-                            top = current_program.top.simplify(state=simplify_state, dynamic=dynamic, path=current_program.path)
-                            now = system_clock()
-                            simplify_time += now
-                            if top is current_program.top:
-                                logger.trace("Program unchanged after simplification on {} static state keys in {:.1f}ms",
-                                             len(self.state_generation2), simplify_time*1000)
-                            else:
-                                compile_time = -now
-                                run_program = top.compile(initial_lnames=tuple(dynamic))
-                                run_program.set_path(current_program.path)
-                                run_program.set_top(top)
-                                compile_time += system_clock()
-                                logger.debug("Simplified on {} static state keys to {} instructions in {:.1f}/{:.1f}ms",
-                                             len(self.state_generation2), len(run_program), simplify_time*1000, compile_time*1000)
-                    self.state_generation1 = self.state_generation0
-                    self.state_generation0 = set()
-                    simplify_state_time = frame_time + self.state_simplify_wait
+                if not self.disable_simplifier and context.stables_changed and current_program is not None:
+                    simplify_time = -system_clock()
+                    top = current_program.top.simplify(dynamic=dynamic, path=current_program.path, stables=stables, stable_cache=stable_cache)
+                    now = system_clock()
+                    simplify_time += now
+                    if top is current_program.top:
+                        logger.trace("Program unchanged after simplification on stable values in {:.1f}ms", simplify_time*1000)
+                    else:
+                        compile_time = -now
+                        run_program = top.compile(initial_lnames=tuple(dynamic), stables=stables)
+                        run_program.set_path(current_program.path)
+                        run_program.set_top(top)
+                        compile_time += system_clock()
+                        logger.debug("Resimplified on stable values to {} instructions in {:.1f}/{:.1f}ms",
+                                     len(run_program), simplify_time*1000, compile_time*1000)
 
                 if self.global_state_dirty and self.state_file is not None and frame_time > save_state_time:
                     logger.trace("Saving state")

src/flitter/language/grammar.lark

@@ -26,6 +26,7 @@ pragma : "%pragma" NAME literal _NL -> binding
 sequence : expression* let_expression?
 
 let_expression : "let" multiline_bindings sequence -> let
+               | "let" "stable" multiline_bindings sequence -> let_stable
                | "let" name_list "=" _NL _INDENT sequence _DEDENT sequence -> sequence_let
                | "func" NAME _LPAREN parameters _RPAREN _NL _INDENT sequence _DEDENT sequence -> function
                | "import" name_list "from" composition _NL sequence ->  let_import

src/flitter/language/parser.py

@@ -146,6 +146,7 @@ def sequence(self, *expressions):
     le = tree.LessThanOrEqualTo
     let = tree.Let
     let_import = tree.Import
+    let_stable = tree.LetStable
     literal = tree.Literal
     logical_and = tree.And
     logical_not = tree.Not

src/flitter/language/tree.pyx

@@ -54,8 +54,8 @@ cdef bint sequence_pack(list expressions):
 cdef class Expression:
     cdef readonly frozenset unbound_names
 
-    def compile(self, tuple initial_lnames=(), set initial_errors=None, bint log_errors=True):
-        cdef Program program = Program.__new__(Program, initial_lnames)
+    def compile(self, tuple initial_lnames=(), set initial_errors=None, bint log_errors=True, set stables=None):
+        cdef Program program = Program.__new__(Program, initial_lnames, stables)
         if initial_errors:
             program.compiler_errors.update(initial_errors)
         self._compile(program, list(initial_lnames))
@@ -65,7 +65,8 @@ cdef class Expression:
                 logger.warning("Compiler error: {}", error)
         return program
 
-    def simplify(self, StateDict state=None, dict static=None, dynamic=None, Context parent=None, path=None, bint return_context=False):
+    def simplify(self, StateDict state=None, dict static=None, dynamic=None, Context parent=None, path=None, bint return_context=False,
+                 set stables=None, dict stable_cache=None):
         cdef dict context_vars = {}
         cdef str key
         if static is not None:
@@ -74,7 +75,7 @@ cdef class Expression:
         if dynamic is not None:
             for key in dynamic:
                 context_vars[key] = None
-        cdef Context context = Context(state=state, names=context_vars)
+        cdef Context context = Context(state=state, names=context_vars, stables=stables, stable_cache=stable_cache)
         context.path = path
         context.parent = parent
         cdef Expression expr = self
@@ -1412,7 +1413,7 @@ cdef class Let(Expression):
         cdef int64_t i, j, n
         cdef bint touched = False
         cdef set shadowed=set(), discarded=set()
-        while type(body) is Let:
+        while type(body) is type(self):
             bindings.extend((<Let>body).bindings)
             body = (<Let>body).body
             touched = True
@@ -1492,29 +1493,99 @@ cdef class Let(Expression):
                         break
                 else:
                     touched = True
-        if type(sbody) is Let:
+        if type(sbody) is type(self):
             remaining.extend((<Let>sbody).bindings)
             sbody = (<Let>sbody).body
             resimplify = True
             touched = True
         if remaining:
             if type(sbody) is Sequence and type((<Sequence>sbody).expressions[0]) is Literal:
                 if len((<Sequence>sbody).expressions) > 2:
-                    sbody = Sequence(((<Sequence>sbody).expressions[0], Let(tuple(remaining), Sequence((<Sequence>sbody).expressions[1:]))))
+                    sbody = Sequence(((<Sequence>sbody).expressions[0], type(self)(tuple(remaining), Sequence((<Sequence>sbody).expressions[1:]))))
                 else:
-                    if type((<Sequence>sbody).expressions[1]) is Let:
+                    if type((<Sequence>sbody).expressions[1]) is type(self):
                         resimplify = True
-                    sbody = Sequence(((<Sequence>sbody).expressions[0], Let(tuple(remaining), (<Sequence>sbody).expressions[1])))
+                    sbody = Sequence(((<Sequence>sbody).expressions[0], type(self)(tuple(remaining), (<Sequence>sbody).expressions[1])))
             elif touched:
-                sbody = Let(tuple(remaining), sbody)
+                sbody = type(self)(tuple(remaining), sbody)
             else:
                 return self
         if resimplify:
             return sbody._simplify(context)
         return sbody
 
     def __repr__(self):
-        return f'Let({self.bindings!r}, {self.body!r})'
+        return f'{type(self).__name__}({self.bindings!r}, {self.body!r})'
+
+
+cdef int StableId = 0
+
+cdef class LetStable(Let):
+    cdef readonly int id
+
+    def __init__(self, tuple bindings, Expression body):
+        global StableId
+        Let.__init__(self, bindings, body)
+        self.id = StableId
+        StableId += 1
+
+    cdef void _compile(self, Program program, list lnames):
+        cdef PolyBinding binding
+        cdef int64_t n=len(lnames)
+        cdef tuple key
+        for i, binding in enumerate(self.bindings):
+            key = (self.id, i)
+            binding.expr._compile(program, lnames)
+            if key in program.stables:
+                program.stable_assert(key)
+            else:
+                program.stable_test(key)
+                program.local_push(len(binding.names))
+                lnames.extend(binding.names)
+        self.body._compile(program, lnames)
+        cdef Instruction instr, compose=None
+        if len(lnames) > n:
+            if program.last_instruction().code == OpCode.Compose:
+                compose = program.pop_instruction()
+            instr = program.last_instruction()
+            if instr.code == OpCode.LocalDrop:
+                program.pop_instruction()
+                program.local_drop((<InstructionInt>instr).value + len(lnames) - n)
+            else:
+                program.local_drop(len(lnames) - n)
+            if compose is not None:
+                program.push_instruction(compose)
+            while len(lnames) > n:
+                lnames.pop()
+
+    cdef Expression _simplify(self, Context context):
+        cdef Expression body, expr = Let._simplify(self, context)
+        if type(expr) is not LetStable:
+            return expr
+        cdef LetStable stable = <LetStable>expr
+        cdef Vector value
+        cdef tuple key
+        cdef bint resimplify = False
+        cdef dict saved = context.names
+        context.names = saved.copy()
+        for i, binding in enumerate(stable.bindings):
+            key = (self.id, i)
+            if key in context.stables:
+                resimplify = True
+                value = context.stable_cache[key]
+                if len(binding.names) == 1:
+                    name = <str>binding.names[0]
+                    context.names[name] = value
+                else:
+                    for j, name in enumerate(binding.names):
+                        context.names[name] = value.item(j)
+        if resimplify:
+            body = stable.body._simplify(context)
+            if body is not stable.body:
+                stable = LetStable(stable.bindings, body)
+        context.names = saved
+        stable.id = self.id
+        return stable
 
 
 cdef class For(Expression):