xtc_reg(3)

---

xtc_reg(3)

named process registry

XTC_REG(3) Library Functions Manual XTC_REG(3)

xtc_reg_create, xtc_reg_destroy, xtc_reg_register, xtc_reg_unregister, xtc_reg_lookup, xtc_reg_whereis, xtc_reg_count, xtc_reg_register_dup, xtc_reg_unregister_pid, xtc_reg_drop_pid, xtc_reg_reaper, xtc_reg_register_mon, xtc_svr_call_name, xtc_reg_members — named process registry

#include <xtc.h>
#include <xtc_reg.h>

int
xtc_reg_create(xtc_reg_t **out);

void
xtc_reg_destroy(xtc_reg_t *r);

int
xtc_reg_register(xtc_reg_t *r, const char *name, xtc_pid_t pid);

int
xtc_reg_unregister(xtc_reg_t *r, const char *name);

int
xtc_reg_lookup(xtc_reg_t *r, const char *name, xtc_pid_t *out);

int
xtc_reg_whereis(xtc_reg_t *r, const char *name, xtc_pid_t *out_pid);

int
xtc_reg_count(const xtc_reg_t *r);

int
xtc_reg_register_dup(xtc_reg_t *r, const char *key, xtc_pid_t pid);

int
xtc_reg_unregister_pid(xtc_reg_t *r, const char *key, xtc_pid_t pid);

int
xtc_reg_drop_pid(xtc_reg_t *r, xtc_pid_t pid);

void
xtc_reg_reaper(void *reg);

int
xtc_reg_register_mon(xtc_reg_t *r, const char *name, xtc_pid_t pid);

int
xtc_svr_call_name(xtc_reg_t *r, const char *name, const void *req, size_t req_size, void **out_reply, size_t *out_size, int64_t timeout_ns);

int
xtc_reg_members(xtc_reg_t *r, const char *key, int (*fn)(xtc_pid_t, void *), void *user);

xtc_reg is a name-to-pid registry. Modeled on Erlang's ‘register/2’ process registration. Lets a process find a peer by canonical name without sharing pid pointers ahead of time.

Names are short strings (up to 64 bytes); re-registering the same name with a different pid replaces the prior binding atomically.

xtc_app owns a registry per app (xtc_app_registry(3)). Multiple registries are permitted for sharded namespaces.

() looks up the pid bound to name, writing it to out_pid (the Erlang ‘whereis spelling of ()’). () returns the number of live registrations in r.

() registers a DUPLICATE-KEY entry: unlike () (one pid per unique name), many pids may share one key, so a key names a GROUP -- the substrate for pub/sub and process groups. Registering the same (key, pid) twice is idempotent. () removes one (key, pid) member (a group leave). () removes pid from EVERY key it appears under (unique names and all duplicate-key groups) and returns the number of entries removed -- the "process left everything" cleanup an embedder calls when a process exits or a connection closes.

() is the CRASH-AWARE registry: spawn one process with this body and the registry as its argument ((loop, xtc_reg_reaper, reg, ...)). It registers itself, then monitors every pid registered via () and calls () automatically when such a pid goes DOWN -- the automatic form of the manual cleanup. It runs until its loop is torn down. xtc_reg_register_mon() registers name -> pid like xtc_reg_register() and, when a reaper is running, arranges the entry to be auto-dropped on the pid's DOWN; with no reaper it is exactly xtc_reg_register().

() is via-dispatch: it looks up name -> pid and then () it, letting a client address a gen_server by registered name instead of holding its pid. It returns XTC_E_NOTFOUND if the name is not registered. () visits every pid registered under key; the callback runs UNDER the registry lock (keep it brief; do not re-enter the registry), a nonzero return stops the walk, and the return value is the number of members visited.

xtc_reg_t *r = xtc_app_registry(app);
xtc_pid_t pid;

/* Bind a name to my process. */
xtc_reg_register(r, "metrics_proc", xtc_self());

/* From elsewhere: */
if (xtc_reg_lookup(r, "metrics_proc", &pid) == XTC_OK)
    xtc_send(pid, msg, sz);

xtc_app(3), xtc_proc(3), xtc(7)

Appeared in xtc 0.1.

May 28, 2026 Debian

View the mdoc source