Skip to content

vgi-rpc C++

C++ implementation of the vgi_rpc framework — Apache Arrow IPC-based RPC for high-performance data services.

Built by Query.Farm

Define RPC methods with typed C++20 handlers using Arrow schemas. The framework provides server dispatch with automatic parameter extraction and result serialization over stdin/stdout pipe transport.

Key Features

  • Unary RPCs with typed parameter extraction via get<T>(name)
  • Producer streams for server-initiated batch data flows
  • Exchange streams for bidirectional batch processing
  • Client-directed logging at configurable levels
  • Introspection via optional __describe__ method
  • Error handling — exceptions automatically converted to protocol error responses
  • Builder pattern — fluent ServerBuilder API for registering methods

Three Method Types

Unary

A single request produces a single response. The client sends parameters, the server returns a result.

Client  ──  add(a=2, b=3)  ──▸  Server
Client  ◂──     5.0         ──  Server

Producer

The server pushes batches to the client until calling out.finish():

Client  ──  produce_n(count=3)  ──▸  Server
Client  ◂──  {index: [0]}       ──  Server
Client  ◂──  {index: [1]}       ──  Server
Client  ◂──  {index: [2]}       ──  Server
Client  ◂──    [finish]         ──  Server

Exchange

Lockstep bidirectional streaming — one request, one response, repeat:

Client  ──  exchange_scale(factor=2.5)  ──▸  Server
Client  ──    {value: [10.0]}           ──▸  Server
Client  ◂──   {value: [25.0]}          ──  Server
Client  ──    {value: [4.0]}            ──▸  Server
Client  ◂──   {value: [10.0]}          ──  Server
Client  ──      [close]                 ──▸  Server

Quick Example

examples/quick_example.cpp
// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
// SPDX-License-Identifier: Apache-2.0

#include <vgi_rpc/server.h>
#include <vgi_rpc/request.h>
#include <vgi_rpc/result.h>
#include <vgi_rpc/arrow_utils.h>

#include <arrow/array/builder_primitive.h>
#include <arrow/type.h>

int main() {
    auto server = vgi_rpc::ServerBuilder()
        .add_unary("add",
            arrow::schema({
                arrow::field("a", arrow::float64()),
                arrow::field("b", arrow::float64()),
            }),
            arrow::schema({arrow::field("result", arrow::float64())}),
            [](const vgi_rpc::Request& req, vgi_rpc::CallContext& ctx) {
                double a = req.get<double>("a");
                double b = req.get<double>("b");

                arrow::DoubleBuilder builder;
                VGI_RPC_THROW_NOT_OK(builder.Append(a + b));
                auto array = vgi_rpc::unwrap(builder.Finish());

                return vgi_rpc::Result::value(
                    arrow::schema({arrow::field("result", arrow::float64())}),
                    {array});
            },
            "Add two numbers together.")
        .enable_describe("MyServer")
        .build();

    server->run();
}

Next Steps

vgi-rpc · Query.Farm