# pharo-project/pharo-vm architecture

> Architecture diagram of the GitHub repository pharo-project/pharo-vm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pharo-project/pharo-vm
- Repository: https://github.com/pharo-project/pharo-vm

## Overview

##### Main Components Identification
- VM Core: Represent the heart of the virtual machine (illustrated by the “extracted/vm” and “src” directories). This part includes the bytecode interpreter and the core execution loop.
- JIT Compiler: Show a separate module for the baseline JIT compiler that translates bytecode (using IR templates and abstract interpretation).
- FFI Subsystem: Represent a module wrapping the libFFI-based interface along with its support for non-blocking (worker-thread based) FFI calls. Files under “ffi” provide evidence of this component.
- Plugin Mechanism: Indicate a plug-in architecture supporting various functionalities (e.g., BitBlt, JPEG, Socket, Locale, etc.). These plugins can be shown as additional modules interacting with the core VM.
- Platform-Specific/OS Abstraction Layers: Include components (like in “src/win”, “src/unix”, “include/pharovm/”) that enable support across different operating systems. Also note Docker files and platform-specific CMake modules (found under the “cmake” directory) for build and deployment.
- Build & Configuration Infrastructure: Although not run-time components, it is beneficial to indicate the dependency relationships with the build system (CMake, Jenkins, and Docker configurations).

##### Relationships and Interactions
- GC as a concurrent (or interleaved) subsystem that interacts with the VM core by managing memory allocation, as well as an independent scanning mechanism.
- How FFI calls are invoked from the VM (perhaps initiated through bytecode primitives) and then handed off to the FFI subsystem, which in turn may use worker threads to execute external functions.

##### Architectural Patterns and Design Principles
- Layered Architecture: At the lowest level, you have platform-specific and build environment modules; above that sits the VM core with the interpreter and associated subsystems; then come the dynamic JIT and GC components, with plugins on the periphery, integrated at runtime.
- Modularity/Plug-in Interface: The clear separation of plugins (in multiple directories such as “extracted/plugins” and “plugins”) suggests a design that encourages extensibility.
- Separation of Concerns: Different directories and file groups control build configurations (CMake, Docker), platform-specific code, and actual VM operational code.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        %% Build & Deployment Subgraph
        subgraph "Build & Deployment"
            BD1("CMake Modules"):::infrastructure
            BD2("Docker Configs"):::infrastructure
            BD3("Jenkins Integration"):::infrastructure
            BD4("CMake Build"):::infrastructure
        end
        %% Platform Abstraction Subgraph
        subgraph "Platform Abstraction Layer"
            PA1("Windows Abstraction"):::infrastructure
            PA2("Unix Abstraction"):::infrastructure
            PA3("Mac Abstraction"):::infrastructure
            PA4("OS Headers"):::infrastructure
        end
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        VM_Core("VM Core"):::runtime
        VM_Runtime("Runtime Loop"):::runtime
        Interpreter("Bytecode Interpreter"):::runtime
        JIT("JIT Compiler"):::runtime
        GC("Garbage Collector"):::runtime
        FFI("FFI Subsystem"):::runtime
    end

    %% Extension Layer
    subgraph "Extension Layer"
        PM1("Plugin Manager (extracted)"):::extension
        PM2("Plugin Manager (plugins)"):::extension
    end

    %% Infrastructure Connections
    BD1 --- PA1
    BD1 --- PA2
    BD1 --- PA3
    BD1 --- PA4

    PA1 --- VM_Core
    PA2 --- VM_Core
    PA3 --- VM_Core
    PA4 --- VM_Core

    BD2 --- VM_Core
    BD3 --- VM_Core
    BD4 --- VM_Core

    %% VM Core internal flow
    VM_Core --> VM_Runtime
    VM_Runtime --> Interpreter

    %% Interpreter interactions with runtime subsystems
    Interpreter -->|"dispatchToJIT"| JIT
    Interpreter -->|"memoryRequest"| GC
    Interpreter -->|"invokeFFI"| FFI

    %% Plugin interactions with core
    PM1 ---|"extendCore"| Interpreter
    PM2 ---|"extendCore"| Interpreter

    %% Styling classes
    classDef runtime fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef infrastructure fill:#A9DFBF,stroke:#1D8348,stroke-width:2px;
    classDef extension fill:#F9E79F,stroke:#B7950B,stroke-width:2px;

    %% Click Events for mapped components
    click VM_Core "https://github.com/pharo-project/pharo-vm/tree/pharo-10/extracted/vm"
    click VM_Runtime "https://github.com/pharo-project/pharo-vm/tree/pharo-10/src"
    click JIT "https://github.com/pharo-project/pharo-vm/blob/pharo-10/include/pharovm/jit/jit.h"
    click GC "https://github.com/pharo-project/pharo-vm/blob/pharo-10/extracted/vm/src/common/sqVirtualMachine.c"
    click FFI "https://github.com/pharo-project/pharo-vm/tree/pharo-10/ffi"
    click PM1 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/extracted/plugins"
    click PM2 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/plugins"
    click PA1 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/src/win"
    click PA2 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/src/unix"
    click PA3 "https://github.com/pharo-project/pharo-vm/blob/pharo-10/src/fileDialogMac.m"
    click PA4 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/include/pharovm"
    click BD1 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/cmake"
    click BD2 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/docker"
    click BD3 "https://github.com/pharo-project/pharo-vm/tree/pharo-10/Jenkinsfile"
    click BD4 "https://github.com/pharo-project/pharo-vm/blob/pharo-10/CMakeLists.txt"
```
