Documentation — RingLoom

RingLoom is a low-latency service messaging runtime built around two paths:

same-host services communicate through memory-mapped shared-memory ring buffers;
brokers route cross-host traffic over framed TCP connections.

These docs focus on using RingLoom from an application and operations perspective. The engineering notes in the main repository remain the deeper implementation reference, while this section gives you the concepts and commands needed to run brokers, start services, observe the system, and understand the sample applications.

Start here

Use these pages in order if you are new to the project:

Quickstart — build the repository, start a broker, run the echo/ping test services, and inspect shared-memory state.
Core Concepts — learn the mental model: nodes, brokers, services, metadata files, ring buffers, service discovery, templates, and routing identifiers.
Operations — configure broker nodes, choose storage paths and buffer sizes, monitor counters, and troubleshoot common failures.
Examples — run the order-management sample and understand the smaller test-service scenarios used by the end-to-end harness.

What RingLoom gives you

Capability	How RingLoom provides it
Local low-latency messaging	Producers write directly into a target service ring buffer through shared memory.
Cross-node routing	Services still send through the same client API; the local broker forwards messages to the target broker over TCP when the target node is remote.
Service discovery	A service subscribes to a target service name and receives complete instance snapshots from the broker.
Load balancing	A `ServiceClient` tracks discovered instances and selects targets with a client-side load balancer.
Leader-aware sends	Services can enable leader election and callers can route to the elected instance.
Observability	Brokers and services publish metadata, counters, ring positions, heartbeat timestamps, and error logs through mapped files that tools can read out-of-process.
Testability	The repository includes unit tests, multi-process end-to-end tests, performance benchmarks, and runnable sample services.

Common commands

From the RingLoom repository root:

zig build test
zig build e2e
zig build perf
zig build run -- --config path/to/broker.properties
zig build stat -- --storage-path /dev/shm --group ringloom
zig build observability
zig build sample-order-management
zig build run-sample-order-management

The broker executable installed by the build is zig-out/bin/ringloom-broker. Test and sample service binaries are installed under zig-out/bin/ as well.

Runtime shape

A typical deployment has one broker per node. Services on the same node register with their local broker and get a service ID. Each broker and service owns a metadata file under:

<storage-path>/<group>/services/

The metadata file contains a fixed header, control ring, message ring, counters, and monitoring regions. The broker control loop processes registration, discovery, heartbeat, and leader-election messages. The sender and receiver event loops move cross-node traffic between broker send rings and TCP peer connections.

For the fastest path, allocate payloads at startup, use fixed layouts such as extern struct, reuse buffers, and prefer the claim/commit API when writing application messages.

docs Quickstart

Install RingLoom, run a broker, and send your first messages.

docs Core Concepts

Understand brokers, services, nodes, ring buffers, templates, and routing identifiers.

docs Operations

Configuration, monitoring, deployment, failure handling, and production checklists.

docs Examples

Walkthroughs for common RingLoom service communication patterns.