xtc_pg(3)

---

xtc_pg(3)

process groups (pub/sub and fan-out)

XTC_PG(3)

Library Functions Manual

XTC_PG(3)

NAME

xtc_pg_join, xtc_pg_leave, xtc_pg_members, xtc_pg_send — process groups (pub/sub and fan-out)

LIBRARY

library “libxtc”

SYNOPSIS

#include <xtc_pg.h>

int
xtc_pg_join(xtc_reg_t *reg, const char *group, xtc_pid_t pid);

int
xtc_pg_leave(xtc_reg_t *reg, const char *group, xtc_pid_t pid);

int
xtc_pg_members(xtc_reg_t *reg, const char *group, int (*fn)(xtc_pid_t, void *), void *user);

int
xtc_pg_send(xtc_reg_t *reg, const char *group, const void *msg, size_t size);

DESCRIPTION

A process group is a named membership set of pids -- the Erlang ‘pg’, Phoenix ‘PubSub’, and Discord-presence pattern. A group is a duplicate-key entry in an xtc_reg(3) registry (see xtc_reg_register_dup()), so many pids share one key.

xtc_pg_join() adds pid to group (idempotent -- a pid already in the group is not added twice). A process typically joins itself with xtc_self().

xtc_pg_leave() removes pid from group, returning XTC_E_INVAL if it was not a member.

xtc_pg_members() visits every member pid. The callback runs UNDER the registry lock, so it must be brief and must not re-enter the registry; copy pids out if more work is needed. A nonzero callback return stops the walk.

xtc_pg_send() broadcasts msg (a copy) to every current member. It collects the member pids under the registry lock and then sends OUTSIDE the lock, so a bounded-mailbox park never happens with the registry lock held. A send to an already-dead member fails harmlessly and is skipped.

RETURN VALUES

xtc_pg_join() and xtc_pg_leave() return XTC_OK on success or a negative XTC_E_* code. xtc_pg_members() returns the number of members visited. xtc_pg_send() returns the number of members the message was successfully sent to.

NOTES

Single node only. Cross-node process groups need the distributed module, which is not built. Until the registry gains a monitor that auto-unregisters a member on its DOWN, a crashed member lingers in the group until something calls xtc_pg_leave() for it; a stale-member xtc_pg_send() is a harmless no-op.

EXAMPLES

xtc_reg_t *r = xtc_app_registry(app);

/* Each subscriber joins the topic. */
xtc_pg_join(r, "chat:lobby", xtc_self());

/* A publisher fans a message out to all subscribers. */
int n = xtc_pg_send(r, "chat:lobby", line, len);
/* n = number of subscribers that received it */