09_shared_memory_bridge

Shared Memory Bridge

The Zero-Copy Shared Memory Bridge

Purpose

The Shared Memory Bridge is the system's high-speed data exchange tool. It allows different programming languages (C++, Python, and Node.js) to share massive amounts of data—like huge tables, grids, or maps—without needing to copy the data back and forth. By using a technique called "memory mapping," ARES ensures that data written by one language is immediately visible to another language.

Why it exists

Normally, moving data between two programs is slow. You have to save the data to a file or turn it into a long string (like JSON), send it over, and then the other program has to rebuild it. When you are dealing with millions of data points, this "copying" can take longer than the actual math. The Bridge exists to eliminate this waste. It creates a single place in your computer's memory that both languages can look at at the same time. This is called Zero-Copy because the data is never moved; it stays in one place, and only the "viewers" change.

How it works

The system uses a special file that acts as a "shared arena" for all your programs.

  1. Creating the Arena. When the compiler starts, it creates a hidden binary file (called ares_shm.bin) that serves as the shared memory space.
  2. Writing the layout. It also creates a small map (a JSON file) that names every piece of data in the arena and explains exactly where it starts and how big it is.
  3. Mapping the memory. Every program that runs (whether it's C++ or Python) "maps" this file into its own memory space. To the program, it looks like a normal list of numbers that is already loaded and ready to use.
  4. Instant access. If a C++ simulation writes a result into the arena, a Python visualization tool can see that result immediately. It doesn't need to read a file or wait for a message; the data is already there.

Intuition

Think of the Shared Memory Bridge like a massive whiteboard in a shared office. Instead of writing a letter and mailing it to your teammate (which is like copying data), you simply write your information on the whiteboard. Your teammate can look over and see exactly what you wrote the moment you finish writing it. You both use the same board, and neither of you has to move your desk or copy the notes.

Implementation details

The coordination of this memory is handled in src/orchestrator/shared_memory.ts. It ensures that every language uses the same binary rules so they don't misunderstand each other's data.

  • Binary Layout: Data is stored in a strict, packed format with no extra spaces.
  • Standards: It uses the same "Little-Endian" format used by almost all modern computers (x86 and ARM).

Trace example

This is what happens when you pass a large grid from C++ to Python for a chart:

  1. C++ (The Producer): Writes the grid directly into the shared arena.
  2. Manifest: The system records that the "grid" starts at byte 0 and has a specific shape.
  3. Python (The Consumer): Uses a tool called np.memmap to look at the same arena file.
  4. Result: Python treats the arena like a native list. It creates the chart immediately without ever "loading" the data into its own private memory.

Related entities

  • 08_orchestrator_daemon.md: The manager that starts the different programs and ensures they all have access to the same arena.
  • 8_registry_approaches/04_data_science.md: Explains the data science tools that are the primary users of this high-speed memory.
ARES