stackvoided/Tenant-Virtualizater

AMX Multi-Tenant Sandbox Engine (v2.0 Enterprise)

Zero-overhead virtualized execution context manager, SIMD-accelerated spatial engine, and isolated memory pool for SA-MP / open.mp server environments.

---

Architecture Overview 📐

AMX Multi-Tenant Sandbox Engine is an enterprise-grade C++20 dynamic shared object designed to solve execution thread contention and memory isolation bottlenecks in standard SA-MP / open.mp runtime environments. By implementing isolated virtualized instances ("tenants"), the engine allows multiple autonomous .amx bytecodes to execute concurrently within a single process space without state corruption or main-thread frame degradation.

┌──────────────────────────────────────────────┐
│              Main Server Process Space       │
└──────────────────────┬───────────────────────┘
                       │
┌──────────────────────▼───────────────────────┐
│       Zero-Lock Network Router (RingBuffer)  │
└──────────────┬───────────────────────┬───────┘
               │                       │
     ┌─────────▼─────────┐   ┌─────────▼─────────┐
     │ Tenant Instance #1│   │ Tenant Instance #2│
     │       (Slab)      │   │       (Slab)      │
     ├───────────────────┤   ├───────────────────┤
     │ • AVX2 Raycast SIMD│   │ • AVX2 Raycast SIMD│
     │ • Memory Protection│   │ • Memory Protection│
     │ • Real-Time Profiler│  │ • Real-Time Profiler│
     └───────────────────┘   └───────────────────┘

Key Engineering Features

• Memory-Isolated Multi-Tenancy: Enables dynamic creation and tearing down of isolated execution sandboxes for independent minigames, sub-servers, or distinct virtual worlds without global server-side effects or crashes.
• Page-Aligned Slab Allocator: Custom mmap / VirtualAlloc memory pool utilizing aligned arena allocation strategies to bypass OS kernel runtime overhead during rapid AMX script dynamic instantiation and destruction.
• Lock-Free Pipeline Network Routing: Atomic, lock-free ring buffer architecture (LockFreeRingBuffer) designed for ultra-low latency packet dispatching and client-to-tenant routing under heavy payload concurrent strain.
• AVX2 / SIMD Vector Mathematics Engine: Hardware-accelerated Ray-OBB/AABB bounding box collision evaluation (RayOBBIntersectionAVX2) executing concurrent floating-point transformations across 128/256-bit registers.
• Low-Level Inline JIT Detouring: Custom x86 memory patcher providing safe runtime hook installation, instruction detouring, and RWX memory protection swapping.
• Nanosecond Performance Profiler: High-resolution internal telemetry engine measuring execution scope overhead with zero-cost RAII timer abstractions.

---

Codebase Structure 🗂

├── AmxHooks.cpp              
├── JitHooks.cpp           
├── JitHooks.h   
├── MemoryPool.h           
├── NetworkRouter.cpp
├── Profiler.h           
├── SkeletalRaycast.cpp   
├── TenantManager.cpp   
├── TenantManager.h   
├── TenantTypes.h     
├── main.cpp
├── Makefile    
└── tenant_virtualizer.inc

💻 Toolchain Requirements

• Target Architecture: x86 / i686 (32-bit mandatory for SA-MP / open.mp process compatibility).
• Linux Toolchain: g++ (C++20 capable), g++-multilib, gcc-multilib, make.
• Windows Toolchain (Cross-Compilation): i686-w64-mingw32-g++ (via mingw-w64).

---

⚙️ Compilation & Build

The build system utilizes a zero-dependency, optimized multi-architecture Makefile.

1. Host Dependencies Setup (Debian / Ubuntu)

sudo apt update
sudo apt install -y build-essential g++-multilib gcc-multilib mingw-w64

2. Building for Linux Target (TenantVirtualizer.so)

make linux

3. Building for Windows Target (TenantVirtualizer.dll)

make windows

4. Cleaning Build Artifacts

make clean

---

🚀 Deployment & Integration

1. Server Configuration

Copy the compiled shared object into your server's plugins/ directory and append it to your runtime server.cfg.

Linux deployment:

plugins TenantVirtualizer.so

Windows deployment:

plugins TenantVirtualizer.dll

2. PAWN Include Integration

Copy tenant_virtualizer.inc to your pawno/include/ directory and include it within your project source:

#include <a_samp>
#include <tenant_virtualizer>

---

📖 Production Usage Example

#include <a_samp>
#include <tenant_virtualizer>

static g_PaintballTenant = -1;

public OnGameModeInit()
{
    g_PaintballTenant = Tenant_CreateInstance(
        "scriptfiles/tenants/paintball_logic.amx",
        TENANT_FLAG_ISOLATE_MEMORY | TENANT_FLAG_PROFILING_ENABLED
    );

    if (g_PaintballTenant != -1)
    {
        printf("[Sandbox Engine] Successfully instantiated tenant ID: %d", g_PaintballTenant);
    }

    return 1;
}

public OnGameModeExit()
{
    if (g_PaintballTenant != -1)
    {
        Tenant_DestroyInstance(g_PaintballTenant);
    }

    return 1;
}

public OnPlayerCommandText(playerid, cmdtext[])
{
    if (!strcmp(cmdtext, "/joinpaintball", true))
    {
        if (g_PaintballTenant == -1)
            return SendClientMessage(playerid, -1, "Tenant instance offline.");

        Tenant_Bind(playerid, g_PaintballTenant);
        SetPlayerVirtualWorld(playerid, 101);
        SendClientMessage(playerid, -1, "Routed to Paintball Sandbox Environment.");

        return 1;
    }

    if (!strcmp(cmdtext, "/leavepaintball", true))
    {
        Tenant_Unbind(playerid);
        SetPlayerVirtualWorld(playerid, 0);
        SendClientMessage(playerid, -1, "Routed back to Global Master Sandbox.");

        return 1;
    }

    return 0;
}

---

📊 PAWN C-ABI API Reference

Execution Bitmask Flags (TenantExecutionFlags)

---

📜 License

Distributed under the MIT License. See LICENSE for further details.