HOW-TO: Authoring and Deploying Polyglot Applications

Purpose

ARES is designed for high-performance polyglot workflows, where a single program can distribute its workload across C++, Python, and Node.js. This guide provides a step-by-step procedure for authoring, compiling, and deploying these multi-backend applications, ensuring that performance-critical data is correctly shared and visualized.

Prerequisites

Compiler Options: Requires --polyglot flag enabled (index.ts:33).
Target Toolchains: All backends (C++, Python, Node) must be available on the deployment machine.

How-To Steps

1. Identify the Workload Bifurcation

Determine which parts of your logic require speed (C++) and which require broad ecosystem support (Python for ML, Node for Web).

2. Author the ARES Source

Create a script (e.g., sim_vis.ares) that explicitly uses multiple intents:

ares
// 1. C++ for heavy computation
read graph as vector<vector<pair<int,int>>>
use dijkstra on graph with start=0

// 2. Python for visualization
plot dist using python

// 3. Node for reporting (Optional)
print "Simulation Complete"

3. Compile in Polyglot Mode

Compile the script to generate separate source files for each backend:

bash
ares compile sim_vis.ares --polyglot --outputDir ./dist

4. Deploying the Artifacts

The output directory will contain:

main.cpp: The simulation core.
visualizer.py: The plotting script.
package.json: For any Node components.
ares_shm.bin: (If data is shared via Zero-Copy Bridge).

5. Execution

Use the ARES Orchestrator to run the polyglot group:

bash
ares run ./dist --execute

Implementation Mapping

ARES Intent vs. Workflow Realization

Step	ARES Component	Developer Action
Routing	Heuristic Profiler	Automatically detects $O(N^2)$ (C++) vs `Plot` (Python).
Data Sharing	SHM Bridge	Maps matrix from `main.cpp` $\to$ `vis.py`.
Orchestration	Daemon	Spawns `run.exe` then `python run.py`.
Output	Stdio Pipe	Captures results from both into a single stream.

Examples

Defining a Manual Backend Hint: If you want to force an ARES block into a specific language while in polyglot mode:

ares
using python {
    print "This block is Python-only"
}

Traces

Trace for sim_vis.ares execution:

Profiler identifies C++ as the primary for monte_carlo.
Profiler identifies Python as the primary for plot.
Compiler generates main.cpp (simulation) and vis.py (plotting).
Daemon spawns main.cpp first, which writes results to ares_shm.bin.
Daemon spawns vis.py second, which reads results from ares_shm.bin instantly.

Edge Cases

Execution Order: ARES typically executes backends sequentially unless specified. If the visualizer is launched before the data is ready, it may crash or display an empty plot.
SHM Cleanup: Remember to call daemon.cleanup() (or the equivalent CLI flag) to remove the temporary memory-mapped binary files after execution.

Failure Modes

Shared Memory Collision: Avoid manually modifying ares_shm.bin while the C++ process is still writing, as this can lead to corrupted results in Python.

Compatibility

Multi-Core: Each backend runs in its own process, taking full advantage of multi-core CPU architectures.

Testing

Polyglot Invariant: tests/polyglot.test.ts runs 10+ simulation-plot pairs and verifies that the total execution time is less than the sum of individual runs due to the zero-copy overhead reductions.

Related Entities

6_compiler_and_runtime/09_shared_memory_bridge.md: Technical details of the data sharing.
6_compiler_and_runtime/08_orchestrator_daemon.md: Implementation of parallel spawning.

Source Attribution

Concept: Derived from Micro-Frontends applied to compiler backends.
Implementation: src/index.ts (Routing), src/orchestrator/daemon.ts (Execution).