#!/usr/bin/env python

"""

A really simple virtual processor employing a simple set of instructions which

ignore low-level operations and merely concentrate on variable access, structure

access, structure allocation and function invocations.

Copyright (C) 2007, 2008 Paul Boddie <paul@boddie.org.uk>

This program is free software; you can redistribute it and/or modify it under

the terms of the GNU General Public License as published by the Free Software

Foundation; either version 3 of the License, or (at your option) any later

version.

This program is distributed in the hope that it will be useful, but WITHOUT

ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more

details.

You should have received a copy of the GNU General Public License along with

this program.  If not, see <http://www.gnu.org/licenses/>.

--------

The execution model of the virtual processor involves the following things:

  * Memory

  * PC (program counter) stack

  * Frame stack (containing invocation frames in use and in preparation plus

                temporary storage)

  * Local frame pointer stack

  * Invocation frame pointer stack

  * Exception handler stack

  * Registers: current value, boolean status value, source value, result,

               current exception, current callable

The memory contains constants, global variable references and program code.

The PC stack contains the return address associated with each function

invocation.

The frame pointer stack tracks the position of frames within the frame stack.

"""

class IllegalInstruction(Exception):

    pass

class IllegalAddress(Exception):

    pass

class EmptyPCStack(Exception):

    pass

class EmptyFrameStack(Exception):

    pass

class RSVPMachine:

    "A really simple virtual processor."

    def __init__(self, memory, objtable, paramtable, clstable, pc=None, debug=0):

        """

        Initialise the processor with a 'memory' (a list of values containing

        instructions and data) and the optional program counter 'pc'.

        """

        self.memory = memory

        self.objtable = objtable

        self.paramtable = paramtable

        self.clstable = clstable

        self.pc = pc or 0

        self.debug = debug

        # Stacks.

        self.pc_stack = []

        self.frame_stack = []

        self.local_sp_stack = []

        self.invocation_sp_stack = []

        self.handler_stack = []

        # Registers.

        self.instruction = None

        self.operand = None

        self.value = None

        self.status = None

        self.source = None

        self.callable = None

        self.result = None

        self.exception = None

    def load(self, address):

        "Return the value at the given 'address'."

        try:

            return self.memory[address]

        except IndexError:

            raise IllegalAddress, address

    def save(self, address, value):

        "Save to the given 'address' the specified 'value'."

        try:

            self.memory[address] = value

        except IndexError:

            raise IllegalAddress, address

    def new(self, size):

        """

        Allocate space of the given 'size', returning the address of the space.

        """

        addr = len(self.memory)

        for i in range(0, size):

            self.memory.append(None)

        return addr

    def push_pc(self, data):

        "Push 'data' onto the PC stack."

        self.pc_stack.append(data)

    def pull_pc(self):

        "Pull a value from the PC stack and return it."

        try:

            return self.pc_stack.pop()

        except IndexError:

            raise EmptyPCStack

    def run(self):

        "Execute code in the memory, starting from the current PC address."

        try:

            while 1:

                self.execute()

        except EmptyPCStack:

            pass

    def execute(self):

        "Execute code in the memory at the current PC address."

        self.instruction = self.load(self.pc)

        self.operand = self.instruction.get_operand()

        instruction_name = self.instruction.__class__.__name__

        if self.debug:

            print "%8d %s" % (self.pc, instruction_name)

        method = self.get_method(instruction_name)

        # Process any inputs of the instruction.

        self.process_inputs()

        next_pc = method()

        # Update the program counter.

        if next_pc is None:

            self.pc += 1

        else:

            self.pc = next_pc

    def get_method(self, instruction_name):

        "Return the handler method for the given 'instruction_name'."

        method = getattr(self, instruction_name, None)

        if method is None:

            raise IllegalInstruction, (self.pc, instruction_name)

        return method

    def process_inputs(self):

        """

        Process any inputs of the current instruction. This permits any directly

        connected sub-instructions to produce the effects that separate

        instructions would otherwise have.

        """

        for input in (self.instruction.input, self.instruction.source):

            if input is not None:

                method = self.get_method(input)

                method()

    def jump(self, addr, next):

        """

        Jump to the subroutine at (or identified by) 'addr'. If 'addr'

        identifies a library function then invoke the library function and set

        PC to 'next' afterwards; otherwise, set PC to 'addr'.

        """

        if isinstance(addr, str):

            getattr(self, addr)()

            return next

        else:

            self.push_pc(self.pc + 2)

            return addr

    # Instructions.

    def LoadConst(self):

        self.value = None, self.operand

    def LoadName(self):

        frame = self.local_sp_stack[-1]

        self.value = self.frame_stack[frame + self.operand]

    def StoreName(self):

        frame = self.local_sp_stack[-1]

        self.frame_stack[frame + self.operand] = self.value

    LoadTemp = LoadName

    StoreTemp = StoreName

    def LoadAddress(self):

        # Preserve context (potentially null).

        self.value = self.load(self.operand)

    def LoadAddressContext(self):

        value = self.load(self.operand)

        # Replace the context with the current value.

        self.value = self.value[1], value[1]

    def StoreAddress(self):

        # Preserve context.

        self.save(self.operand, self.value)

    def MakeObject(self):

        # Introduce null context for new object.

        self.value = None, self.new(self.operand)

    def LoadAttr(self):

        context, ref = self.value

        # Retrieved context should already be appropriate for the instance.

        self.value = self.load(ref + self.operand)

    def StoreAttr(self):

        context, ref = self.value

        # Target should already be an instance.

        self.save(ref + self.operand, self.source)

    def LoadAttrIndex(self):

        context, ref = self.value

        code = self.load(ref) # + 0 (the classcode)

        element = self.objtable[code + self.operand]

        found_code, class_attr, replace_context, offset = element

        if found_code == code:

            if class_attr:

                loaded_context, loaded_ref = self.load(offset) # offset is address of class attribute

                if replace_context:

                    self.value = ref, loaded_ref # classes can also replace the context if compatible

                    return

                self.value = loaded_context, loaded_ref

            else:

                self.value = self.load(ref + offset)

        else:

            # NOTE: This should cause an attribute error.

            raise Exception, "LoadAttrIndex % r" % element

    def StoreAttrIndex(self):

        context, ref = self.value

        code = self.load(ref) # + 0 (the classcode)

        element = self.objtable[code + self.operand]

        found_code, class_attr, replace_context, offset = element

        if found_code == code:

            if class_attr:

                # NOTE: This should cause an attribute or type error.

                # Class attributes cannot be changed at run-time.

                raise Exception, "StoreAttrIndex % r" % element

            else:

                self.save(ref + offset, self.source)

        else:

            # NOTE: This should cause an attribute error.

            raise Exception, "StoreAttrIndex % r" % element

    # NOTE: LoadAttrIndexContext is a possibility if a particular attribute can always be overridden.

    def MakeFrame(self):

        self.invocation_sp_stack.append(len(self.frame_stack))

        self.frame_stack.extend([None] * self.operand)

    def DropFrame(self):

        self.local_sp_stack.pop()

        frame = self.invocation_sp_stack.pop()

        self.frame_stack = self.frame_stack[:frame] # reset stack before call

    def StoreFrame(self):

        frame = self.invocation_sp_stack[-1] # different from the current frame after MakeFrame

        self.frame_stack[frame + self.operand] = self.value

    def StoreFrameIndex(self):

        frame = self.invocation_sp_stack[-1] # different from the current frame after MakeFrame

        code = self.load(ref) # + 0 (the functioncode)

        element = self.objtable[code + self.operand]

        found_code, offset = element

        if found_code == code:

            self.frame_stack[frame + offset] = self.value

        else:

            # NOTE: This should cause an argument error.

            raise Exception, "StoreFrameIndex % r" % element

    def LoadCallable(self):

        context, ref = self.value

        self.callable = self.load(ref + 1)

    def StoreCallable(self):

        context, ref = self.value

        self.save(ref + 1, self.callable)

    def LoadContext(self):

        context, ref = self.value

        self.value = None, context

    def CheckFrame(self):

        context, ref = self.value

        nargs, ndefaults = self.load(ref + 2)

        if not (nargs - ndefaults <= self.operand <= nargs):

            raise Exception, "CheckFrame %r" % (nargs - ndefaults, self.operand, nargs)

        # NOTE: Support population of defaults.

        # NOTE: Support sliding of the frame to exclude any inappropriate context.

    def CheckSelf(self): pass

    def JumpWithFrame(self):

        self.local_sp_stack.append(self.invocation_sp_stack[-1]) # adopt the invocation frame

        return self.jump(self.callable, self.pc + 1) # return to the instruction after this one

    def ExtendFrame(self):

        frame = self.local_sp_stack[-1]

        frame.extend([None] * self.operand)

    def Return(self):

        self.pc = self.pull_pc()

    def LoadResult(self):

        self.value = self.result

    def StoreResult(self):

        self.result = self.value

    def Jump(self):

        return self.operand

    def JumpIfTrue(self):

        if self.status:

            return self.operand

    def JumpIfFalse(self):

        if not self.status:

            return self.operand

    def LoadException(self):

        self.value = self.exception

    def StoreException(self):

        self.exception = self.value

    def RaiseException(self):

        return self.handler_stack.pop()

    def PushHandler(self):

        self.handler_stack.append(self.operand)

    def PopHandler(self):

        self.handler_stack.pop()

    def CheckException(self):

        self.status = self.value[1] == self.exception

    def TestIdentity(self):

        self.status = self.value[1] == self.source

    def TestIdentityAddress(self):

        self.status = self.value[1] == self.operand

    # LoadBoolean is implemented in the generated code.

    # StoreBoolean is implemented by testing against the True value.

    def InvertBoolean(self):

        self.status = not self.status

# vim: tabstop=4 expandtab shiftwidth=4