GiocciPlatform

GiocciPlatform is a resource-permeating computing platform for wide-area distributed systems.

Overview

This repository contains the GiocciPlatform, which enables distributed code execution across wide-area networks. The platform consists of three main components and an integration test suite:

• Giocci - Client library for sending modules and executing functions on remote engines
• GiocciRelay - Relay component that manages client/engine registration and routes requests
• GiocciEngine - Execution engine that loads modules and executes functions
• GiocciIntegrationTest - Integration test suite that verifies end-to-end functionality across all components

All components communicate over Zenoh, a pub/sub/query protocol for distributed systems.

Components

Giocci

An Elixir library that allows applications to:

• Register with a relay
• Save Elixir modules to remote engines
• Execute functions synchronously or asynchronously

Installation and usage: See apps/giocci/README.md

Hex package: giocci

GiocciRelay

A relay service that:

• Manages client and engine registrations
• Stores and distributes modules to engines
• Routes execution requests between clients and engines

Deployment guide: See apps/giocci_relay/README.md

GiocciEngine

An execution engine that:

• Receives and loads modules dynamically
• Executes functions on behalf of clients
• Returns results synchronously or asynchronously

Deployment guide: See apps/giocci_engine/README.md

GiocciIntegrationTest

An integration test suite that:

• Verifies end-to-end functionality across all components
• Tests client registration, module distribution, and remote execution
• Validates error handling when components are unavailable
• Includes both synchronous and asynchronous execution scenarios

Test guide: See apps/giocci_integration_test/README.md

Prerequisites

All components require:

• Zenoh daemon (zenohd) running and accessible

Quick Start

1. Deploy GiocciRelay: Follow apps/giocci_relay/README.md

2. Deploy GiocciEngine: Follow apps/giocci_engine/README.md

3. Try it out: Follow the "Running with Docker" section in apps/giocci/README.md to test the platform

4. Use in your application: Once you're familiar with the platform, integrate Giocci into your Elixir application. See the Installation and Usage sections in the Giocci README

The giocci_example repository provides the example code and its instruction for Giocci Client.

Architecture

Components

• Client: apps/giocci
• Relay: apps/giocci_relay
• Engine: apps/giocci_engine
• Transport: Zenohex (Zenoh) session

Communication Flow

This platform communicates over Zenohex (Zenoh) using Query/Reply and Pub/Sub patterns.

Key Map

• Client registration: giocci/register/client/{relay_name}
• Engine registration: giocci/register/engine/{relay_name}
• Save module (Client -> Relay): giocci/save_module/client/{relay_name}
• Distribute module (Relay -> Engine): giocci/save_module/relay/{engine_name}
• Engine inquiry: giocci/inquiry_engine/client/{relay_name}
• Sync exec request: giocci/exec_func/client/{engine_name}
• Async exec request (Engine subscribes): giocci/exec_func_async/client/{engine_name}
• Async exec result (Client subscribes): giocci/exec_func_async/engine/{client_name}
• If key_prefix is set, it is prepended (e.g., prefix/giocci/...).

Flows

1) Client Registration

sequenceDiagram
  participant Client
  participant Relay
  participant Engine

  Client->>Relay: Query giocci/register/client/{relay}
  Relay->>Relay: register client
  Relay->>Client: Reply :ok

Loading

2) Engine Registration + Existing Module Distribution

sequenceDiagram
  participant Client
  participant Relay
  participant Engine

  Engine->>Relay: Query giocci/register/engine/{relay}
  Relay->>Relay: fetch existing modules from ModuleStore
  Relay->>Engine: Query giocci/save_module/relay/{engine}
  Engine->>Engine: :code.load_binary
  Engine->>Relay: Reply :ok
  Relay->>Engine: Reply :ok (registration complete)

Loading

3) Save Module (Client -> Relay -> Engine)

sequenceDiagram
  participant Client
  participant Relay
  participant Engine

  Client->>Relay: Query giocci/save_module/client/{relay}
  Relay->>Relay: validate client + ModuleStore.put
  Relay->>Engine: Query giocci/save_module/relay/{engine}
  Engine->>Engine: :code.load_binary
  Engine->>Relay: Reply :ok
  Relay->>Client: Reply :ok

Loading

4) Sync Execution (Client -> Relay -> Engine -> Client)

sequenceDiagram
  participant Client
  participant Relay
  participant Engine

  Client->>Relay: Query giocci/inquiry_engine/client/{relay}
  Relay->>Relay: select engine
  Relay->>Client: Reply {engine_name}

  Client->>Engine: Query giocci/exec_func/client/{engine}
  Engine->>Engine: validate module + exec
  Engine->>Client: Reply result

Loading

5) Async Execution (Client -> Relay -> Engine -> Client)

sequenceDiagram
  participant Client
  participant Relay
  participant Engine

  Client->>Relay: Query giocci/inquiry_engine/client/{relay}
  Relay->>Relay: select engine
  Relay->>Client: Reply {engine_name}

  Client->>Engine: Put giocci/exec_func_async/client/{engine}
  Engine->>Engine: exec and build result
  Engine->>Client: Put giocci/exec_func_async/engine/{client}
  Client->>Client: send {:giocci, result}

Loading

Notes

• Client <-> Relay uses Query/Reply; Engine uses Queryable for sync and Subscriber/Publisher for async.
• All communication is via Zenohex key space; key_prefix may be prepended.
• Engine selection is currently first-registered in GiocciRelay.EngineRegistrar.select_engine/0.
• Modules dynamically defined in IEx (without a corresponding object file) are not supported.

For Developers

See FOR_DEVELOPERS.md for development instructions, testing, and release procedures.

Publication (Papers/Presentations)

• [Presentation (Slide | Video)] Giocci: a resource-permeating computing platform for wide-area distributed systems
  • Goatmire Elixir 2025 @ Varberg, Sweden
  • Hideki Takase and Yutaka Kikuchi
• [Paper in Japanese] A wide-area distributed processing method by integrating communication protocol Zenoh into resource permeating computing platform Giocci (資源透過型プラットフォームGiocciへの通信プロトコルZenohの統合による広域分散処理手法)
  • IPSJ SIG Report, Vol. 2025-ARC-260, No. 5.
  • Keiya Ito, Shintaro Hosoai, Kazuma Nishiuchi, Mitsuhiro Osaki, Yutaka Kikuchi, Satoru Matsushima and Hideki Takase
• [Paper in Japanese] Giocci: A distributed computation platform that permeably handles computation resources on MEC and papric clouds on 5G networks (5GネットワークのMECとパプリッククラウド上の計算資源を透過的に扱う分散計算プラットフォームの提案)
  • IPSJ SIG Report, Vol. 2023-IOT-61, No. 20.
  • Mitsuhiro Osaki, Kazuma Nishiuchi, Ikuo Nakagawa, Hideki Takase, Shintaro Hosoai, Shunsuke Kikuchi and Yutaka Kikuchi