# harbour/core architecture

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

- Interactive diagram: https://gitdiagram.com/harbour/core
- Repository: https://github.com/harbour/core

## Overview

##### “virtual machine” scope
- The “vm” directory (src/vm) contains the core files that implement execution.
- These include files for array and object management (arrays.c, arrayshb.c), instruction execution (eval.c, evalhb.c), control flow (break.c, proc.c), memory allocation (dlmalloc.c, memvars.c), class handling (classes.c), and system routines (initexit.c, initsymb.c, thread.c, task.c).
- Although the compiler is separate (in the src/compiler folder), the output of compilation – the intermediate bytecode – is executed by the VM. Note that the virtual machine is one of the central runtime “engines” of Harbour.

##### Main components of the VM
- Instruction Execution Loop:
– Represent the core interpreter cycle. Include “fetch,” “decode” and “execute” stages.
– Show how the compiled Harbour bytecode, generated by the compiler, is sent into the VM.
– Files such as eval.c and evalhb.c are key here.
- Memory Management & Data Storage:
– Include components for the heap and allocation, e.g., files like dlmalloc.c.
– Show “Memory Blocks,” “Dynamic variables management” (memvars, memvclip) and symbol table handling (initsymb).
- Object and Class System:
– Highlight the submodule that handles classes and objects (classes.c, possibly parts in vm related to built-in methods).
- Execution Control & Flow:
– Represent break/loop control and task scheduling. Files such as break.c, task.c, and thread.c provide support here.
- Runtime Built-in Functions and API Layer:
- Debugging and Exception (Tracing/Error) Facilities:
- External Interfaces:
– Optionally illustrate how the VM interacts with the rest of the runtime ecosystem (for example, linking to native libraries through dynamic linking routines and communicating with the OS).

##### Architectural Patterns and Technologies
- That the VM design uses a “fetch–decode–execute” cycle pattern typical in interpreters.
- A note on “garbage collection / memory management” if applicable (Harbour combines manual memory tracking with auto-managed variables).
- That the VM is multi-threaded by connecting the “Thread and Task Manager” into the execution control.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Compiler["Compiler (Bytecode Generator)"]:::external
    Compiler -->|"sends_bytecode"| B1

    subgraph "Harbour Virtual Machine"
        B1["Bytecode Interpreter (Fetch-Decode-Execute)"]:::instructionExecution
        B7["Initialization & Symbol Table Management"]:::initSymbol
        B2["Memory Manager & Data Storage"]:::memoryManagement
        B3["Object & Class System"]:::objectSystem
        B4["Execution Control & Flow"]:::executionControl
        B6["Multi-threading & Task Scheduling"]:::threading
        B5["Debug/Trace System"]:::debugSystem
        B8["External Interfaces (Dynamic Linking)"]:::external
    end

    B7 -->|"provides_symbols"| B1
    B2 -->|"supports_memory_for"| B1
    B2 -->|"supports_objects_for"| B3
    B1 -->|"passes_control_to"| B4
    B4 -->|"manages_threads_via"| B6
    B5 -->|"feeds_back_to"| B4
    B4 -->|"calls"| B8

    %% Click Events
    click B1 "https://github.com/harbour/core/blob/master/src/vm/eval.c"
    click B1 "https://github.com/harbour/core/blob/master/src/vm/evalhb.c"
    click B2 "https://github.com/harbour/core/blob/master/src/vm/dlmalloc.c"
    click B2 "https://github.com/harbour/core/blob/master/src/vm/memvars.c"
    click B3 "https://github.com/harbour/core/blob/master/src/vm/classes.c"
    click B4 "https://github.com/harbour/core/blob/master/src/vm/break.c"
    click B4 "https://github.com/harbour/core/blob/master/src/vm/proc.c"
    click B5 "https://github.com/harbour/core/blob/master/src/vm/debug.c"
    click B6 "https://github.com/harbour/core/blob/master/src/vm/thread.c"
    click B6 "https://github.com/harbour/core/blob/master/src/vm/task.c"
    click B7 "https://github.com/harbour/core/blob/master/src/vm/initexit.c"
    click B7 "https://github.com/harbour/core/blob/master/src/vm/initsymb.c"
    click B8 "https://github.com/harbour/core/blob/master/src/vm/dynlibhb.c"

    %% Styles
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef instructionExecution fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef memoryManagement fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef objectSystem fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef executionControl fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef debugSystem fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef threading fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef initSymbol fill:#B0E0E6,stroke:#333,stroke-width:2px;
```
