Quickstart

This guide gets a local RingLoom checkout running with one broker and two test services. You will build the broker, create a small broker config, start an echo service, send messages from a ping service, and inspect the broker metadata.

Prerequisites

• Linux
• Zig matching the version used by this checkout.
• On Linux, shared-memory examples use /dev/shm by default. For local experiments you can also use a temporary directory such as /tmp/ringloom-quickstart/storage.

Run all commands from the ringloom repository root.

1. Build the broker and test services

zig build test
zig build install
zig build test-bins

This builds the core modules, installs ringloom-broker, and installs the small test services used by the end-to-end harness:

• ringloom-test-echo-service
• ringloom-test-ping-service
• ringloom-test-forwarder-service
• ringloom-test-leader-service
• ringloom-test-slow-consumer-service
• ringloom-test-crashy-service

2. Create a single-node broker config

Create a workspace and a broker properties file:

mkdir -p /tmp/ringloom-quickstart/storage
cat > /tmp/ringloom-quickstart/broker.properties <<'EOF'
broker.node.id=1
broker.local.host.port=127.0.0.1:19001
broker.group.name=quickstart
broker.storage.path=/tmp/ringloom-quickstart/storage
broker.control.buffer.size=65536
broker.messages.buffer.size=1048576
broker.threading.mode=dedicated
broker.idle.strategy=backoff
EOF

broker.member.host.ports is intentionally omitted. A broker with no peers is a single-node cluster and elects itself as leader.

3. Start the broker

In terminal 1:

zig build run -- --config /tmp/ringloom-quickstart/broker.properties

You can also run the installed executable directly:

zig-out/bin/ringloom-broker --config /tmp/ringloom-quickstart/broker.properties

The broker creates its metadata file under:

/tmp/ringloom-quickstart/storage/quickstart/services/

4. Start an echo service

In terminal 2:

zig-out/bin/ringloom-test-echo-service \
  --storage-path /tmp/ringloom-quickstart/storage \
  --group quickstart \
  --service-name echo \
  --broker-node-id 1 \
  --max-messages 10

The echo service starts a RingLoomEngine, creates its service metadata file, registers with the broker, starts heartbeat updates, installs a message handler, and waits for incoming messages.

5. Send messages with the ping service

In terminal 3:

zig-out/bin/ringloom-test-ping-service \
  --storage-path /tmp/ringloom-quickstart/storage \
  --group quickstart \
  --service-name ping \
  --target-service echo \
  --broker-node-id 1 \
  --message-count 10 \
  --message-size 64

The ping service starts its own engine, creates a ServiceClient for echo, subscribes to service discovery updates, waits briefly for discovery to propagate, and sends the requested messages. Because both services are on node 1, the client writes directly to the echo service’s message ring buffer through the same-host IPC path.

6. Inspect runtime state

Use ringloom-stat while the broker or services are running:

zig build stat -- --storage-path /tmp/ringloom-quickstart/storage --group quickstart

The output shows broker and service metadata, ring capacities, used/free bytes, producer and consumer positions, heartbeat ages, and allocated counters.

7. Try the full sample

The order-management sample starts two brokers and six services. It demonstrates both local shared-memory IPC and cross-broker TCP routing:

zig build sample-order-management
zig build run-sample-order-management -- --profile default

For a larger run with leader election, duplicate services, and lifecycle events:

zig build run-sample-order-management -- --profile full --orders 100000 --rate-per-sec 50000

Clean up

Stop the service processes first, then stop the broker. For the quickstart workspace, remove temporary metadata with:

rm -rf /tmp/ringloom-quickstart

If a broker or service exits unexpectedly, stale metadata files may remain. The runtime and tools tolerate stale files, but removing the workspace is the simplest way to reset a local experiment.