Rheo is usually started under your supervision tree. Application config sets defaults; per-call and per-consumer options override them.
Prefer explicit supervision
children = [
{Rheo, name: MyRheo, backend: {Rheo.Backend.Mongo, url: mongo_url}},
{MyApp.RiskConsumer, rheo: MyRheo}
]
Supervisor.start_link(children, strategy: :one_for_one)Pass :rheo on public APIs when you use a non-default instance name.
Application environment
config :rheo,
# Do not auto-start under Rheo.Application (default: false)
start_on_application: false,
# Defaults used by fetch / Group / Producer when opts omit them
default_lease_ms: 30_000,
default_max_attempts: 5,
default_max_demand: 10,
# Clock used for lease expiry (tests: Rheo.Clock.Frozen)
clock: Rheo.Clock.System,
# Backend timeouts
ets_call_timeout: 5_000,
mnesia_call_timeout: 5_000,
ecto_call_timeout: 5_000| Key | Purpose |
|---|---|
:start_on_application | When true and a backend is configured, Rheo starts under Rheo.Application |
:backend | Module or {module, opts} for auto-start / Application helper |
:mongo_url | Mongo URL when auto-starting the Mongo backend |
:name | Instance name when auto-starting (default Rheo) |
:default_lease_ms | Lease TTL |
:default_max_attempts | Attempts before dead-letter on nack |
:default_max_demand | Outstanding lease bound |
:clock | Rheo.Clock implementation |
:topology | Legacy Mongo handle name (prefer instance :backend opts) |
Auto-start (optional)
config :rheo,
start_on_application: true,
backend: Rheo.Backend.ETS
# or: mongo_url: "mongodb://localhost:27017/rheo"Most apps should leave this off and supervise {Rheo, …} themselves.
Consumer / Producer options
Rheo.Consumer and Rheo.Producer accept:
| Option | Meaning |
|---|---|
:stream / :group | Required identity |
:rheo | Instance name |
:max_demand | Max unsettled leases |
:lease_ms | Lease TTL; renewal runs at half TTL |
:poll_ms | Idle poll when demand is unmet |
:consumer_id | Worker identity on leases |
:partitions | :all or a list of partition ids |
:concurrency | Handler concurrency (Rheo.Consumer only) |
:on_failure | :nack or :reject (Rheo.Producer / Broadway) |
Multiple instances
children = [
{Rheo, name: RheoRisk, backend: {Rheo.Backend.Mongo, url: url_a}},
{Rheo, name: RheoAudit, backend: {Rheo.Backend.Ecto, repo: MyApp.Repo}}
]
Rheo.append("events", %{…}, rheo: RheoRisk)
Rheo.fetch("events", "risk", rheo: RheoAudit)Each instance has its own backend handle, registry, and group supervisor.
Multi-node BEAM deployments
Several BEAM nodes can run Rheo Groups against the same durable store. Rheo does not manage cluster membership — the backend fences leases.
| Backend | distributed | Multi-node OK? |
|---|---|---|
| Redis | true | Yes |
| Ecto PostgreSQL | true | Yes |
| Ecto SQLite | false | No |
| Mongo | false (cap) | Shared Mongo works in practice; flag stays conservative |
| ETS | false | No |
| Mnesia (v0.11) | false | Single-node disc_copies only |
Details: Building your own backend.