diff --git a/projects/shoggoth/src/python/ichor/interpreter.py b/projects/shoggoth/src/python/ichor/interpreter.py index 81aa737..956e680 100644 --- a/projects/shoggoth/src/python/ichor/interpreter.py +++ b/projects/shoggoth/src/python/ichor/interpreter.py @@ -1,10 +1,13 @@ #!/usr/bin/env python3 -"""The Ichor VM.interpreterementation. +"""The Ichor VM implementation. -The whole point of Shoggoth is that program executions are checkpointable and restartable. This requires that rather than -using a traditional recursive interpreter which is difficult to snapshot, interpretation in shoggoth occur within a -context (a virtual machine) which DOES have an easily introspected and serialized representation. +The whole point of Shoggoth is that program executions are checkpointable and restartable. Unfortunately it's difficult +to implement such snapshotting and introspection using a traditional recursive evaluator. It is however VERY easy to +bolt those capabilities onto a VM in a meaninful way. Just provide ways to break, pause or single-step the interpreter +and capture the resulting state(s). + +The VM provides exactly these capabilities, along with some niceties for extensible error recovery and introspection. """ @@ -90,6 +93,7 @@ class BaseInterpreter(object): # "return" via raising InterpreterRestart if that's the desired behavior. Otherwise it's too easy to put the # interpreter into screwy states where an instruction is half-executed and we want to resume execution at that # fine-grained undefined point. + """Handler for interpreter errors. Called when the interpreter encounters an illegal or incorrect state.