PhasorVM.hpp

Go to the documentation of this file.

// Copyright 2026 Daniel McGuire
// Licensed under the Apache License (with LLVM-Exceptions), Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// https://llvm.org/LICENSE.txt
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 
// README
//
// Because the VM is such a complex component, this readme only covers
// basic high-level use cases.
// For more information, please refer to the below, and the internal header
// at src/Runtime/VM/VM.hpp, as well as the [doxygen](phasor-docs.pages.dev)
//
// Usage:
// ```cpp
// // Initialize VM
// Phasor::VM vm;
// // Run bytecode
// vm.run(bytecode);
// ```
 
#pragma once
 
#include <vector>
#include <filesystem>
#include <functional>
#include <map>
#include <array>
#include <ranges>
#include <iostream>
#include <stdexcept>
#include <memory_resource>
 
#ifndef SANDBOXED
#include "PhasorFFI.hpp"
#endif
#include "PhasorISA.hpp"
#include "../Value.hpp"
#include <platform.h>

namespace Phasor
{

class VM
{
  public:
    VM();
    VM(const Bytecode &bytecode);
    VM(const OpCode &op, const int &operand1 = 0, const int &operand2 = 0, const int &operand3 = 0);
    ~VM();

    void initFFI(const std::filesystem::path &path);

    std::string getVersion();

    class Halt : public std::exception
    {
      public:
        const char *what() const noexcept override
        {
            return "";
        }
    };

    int run(const Bytecode &bytecode, const size_t startPC = 0);

    Value runFunction(const std::string &name, const Bytecode &bytecode);

    using NativeFunction = std::function<Value(const std::vector<Value> &args, VM *vm)>;

    void registerNativeFunction(const std::string &name, NativeFunction fn);
 
    using ImportHandler = std::function<void(const std::filesystem::path &path)>;
    void setImportHandler(const ImportHandler &handler);

    void freeVariable(size_t index);

    void freeVariableByName(const std::string &name);

    size_t addVariable(const Value &value);

    void setVariable(size_t index, const Value &value);

    Value getVariable(size_t index);

    size_t getVariableCount();

    void setRegister(uint8_t index, const Value &value);

    void freeRegister(uint8_t index);

    Value getRegister(uint8_t index);

    size_t getRegisterCount();

    enum Register : uint8_t
    {
        r0,
        r1,
        r2,
        r3,
        r4,
        r5,
        r6,
        r7,
        r8,
        r9,
        r10,
        r11,
        r12,
        r13,
        r14,
        r15,
        r16,
        r17,
        r18,
        r19,
        r20,
        r21,
        r22,
        r23,
        r24,
        r25,
        r26,
        r27,
        r28,
        r29,
        r30,
        r31
    };
 
#define REGISTER1 VM::Register::r0
#define REGISTER2 VM::Register::r1
#define REGISTER3 VM::Register::r2
 
#ifdef _WIN32
    Value __fastcall operation(const OpCode &op, const int &operand1 = 0, const int &operand2 = 0,
                               const int &operand3 = 0);
#else
    Value operation(const OpCode &op, const int &operand1 = 0, const int &operand2 = 0, const int &operand3 = 0);
#endif
    void push(const Value &value);

    Value pop();

    Value peek();

    void cleanup();

    void reset(const bool &resetStack = true, const bool &resetFunctions = true, const bool &resetVariables = true);

    std::string getInformation();

    std::string getBytecodeInformation();

    void log(const Value &msg);

    void logerr(const Value &msg);

    void flush();

    void flusherr();

    void setStatus(int newStatus);
    void resetStatus();
    int  getStatus();

    template <typename... Args> inline Value regRun(OpCode opcode, Args &&...args)
    {
        int regIndex = 0;
        (setRegister(regIndex++, std::forward<Args>(args)), ...);
        operation(opcode);
        return getRegister(REGISTER1);
    }

    template <typename... Args> inline Value stackRun(OpCode opcode, Args &&...args)
    {
        Value arr[] = {Value(std::forward<Args>(args))...};
        for (Value &v : arr | std::views::reverse)
            push(v);
        operation(opcode);
        return pop();
    }
 
  private:
    void setup(const Bytecode &bc, const size_t initialPC);
    void evalLoop();
 
    bool isDirectCall = false; 
 
#ifndef SANDBOXED
    std::unique_ptr<FFI> ffi;
#endif
    int status = 0;

    ImportHandler importHandler;

    std::array<Value, MAX_REGISTERS> registers;
    
    std::pmr::monotonic_buffer_resource stack_pool;
    std::pmr::vector<Value> stack;

    std::vector<int> callStack;

    std::vector<Value> variables;

    const Bytecode *m_bytecode{};

    size_t pc = 0;

    std::map<std::string, NativeFunction> nativeFunctions;
};
} // namespace Phasor