Process Groups

Join processes into named groups and broadcast to every member across the cluster. Modeled on Erlang/OTP pg: groups are dynamic, a process can belong to many groups, and membership is tracked cluster-wide and is eventually consistent.

For the scope entry kind and its configuration, see Process Groups. For the broader clustering model, see the Cluster Guide.

Loading

local pg = require("pg")

Opening a Scope

A process group lives inside a scope — a pg.scope registry entry. Open it to get an instance you operate on:

local group, err = pg.open("app:pg")
if err then
    return nil, err
end

Returns: pg.Instance, error

Permission: pg.open on the scope id

The instance is released automatically when the process exits; call release() to free it earlier. All other operations are methods on the instance, called with :.

Joining and Leaving

local ok, err = group:join("workers")           -- single group
local ok, err = group:join({"workers", "all"})  -- batch
local ok, err = group:leave("workers")

Returns: boolean, error

A process may join the same group more than once; it must leave the same number of times to fully depart (multi-join semantics). leave is best-effort across a batch and returns an error only when the process was a member of none of the named groups.

Permissions: pg.join / pg.leave on each group name

Listing Members

local members, err = group:get_members("workers")        -- all nodes
local local_members, err = group:get_local_members("workers")  -- this node only

Returns: string[], error — an array of PID strings (empty for an unknown group)

Permissions: pg.get_members / pg.get_local_members on the group name

Listing Groups

local groups, err = group:which_groups()         -- all groups in the cluster
local local_groups, err = group:which_local_groups()  -- groups with a local member

Returns: string[], error — group names that currently have at least one member

Permissions: pg.which_groups / pg.which_local_groups

Broadcasting

Send a message to every member of a group. Each member receives it under topic from the calling process — handle it with process.listen(topic).

local ok, err = group:broadcast("workers", "task", {id = 42})   -- all nodes
local ok, err = group:broadcast_local("workers", "task", {id = 42})  -- this node only

Returns: boolean, error

Permissions: pg.broadcast / pg.broadcast_local on the group name

Monitoring a Group

monitor subscribes to join/leave events for one group and returns the current members atomically — no membership change can slip between the snapshot and the subscription.

local sub, members, err = group:monitor("workers")
if err then
    return nil, err
end

for _, pid in ipairs(members) do
    -- current members at subscription time
end

local ch = sub:channel()
local event = ch:receive()  -- {kind = "member.joined" | "member.left", path = "workers", data = {...}}

sub:close()  -- unsubscribe; sub:close({flush = true}) drains queued events first

Returns: pg.Subscription, string[], error — the subscription and a snapshot of current members

Permission: pg.monitor on the group name

Watching All Groups

events subscribes to membership changes across every group in the scope and returns a snapshot of all groups to their members.

local sub, snapshot, err = group:events()
-- snapshot: { ["workers"] = {pid, ...}, ["all"] = {pid, ...} }

local event = sub:channel():receive()
sub:close()

Returns: pg.Subscription, table, error

Permission: pg.events

Event Fields

Events delivered on a subscription channel carry:

Subscription channels are buffered (capacity 64). If a slow consumer fills the buffer, further events are retained in the process mailbox in order and delivered once the consumer drains the channel (the subscription stalls rather than dropping events).

Releasing

group:release()

Frees the instance immediately. Idempotent; after release, every method returns an error. Cleanup also runs automatically when the process exits.

Returns: boolean

Permissions

Errors

See Error Handling for working with errors.

See Also

• Process Groups - Scope entry kind and configuration
• Cluster - Membership, naming, and the clustering model
• Process Management - Spawning and messaging individual processes