Discovery and the registrar

Every actor registers its (name, uuid) and transport addresses with a registrar actor — by default the root of the tree, or whichever actor serves at the registry_addrs you boot with. The discovery API lets any actor look up any other by name and get back a connected Portal, giving you service-discovery patterns (daemons, service trees, multi-host meshes) without hard-coding addresses.

Lookups first scan already-connected peers before RPC-ing the registrar, and multihomed results are ranked UDS > local TCP > remote TCP. See examples/service_daemon_discovery.py for the canonical daemon + lookup pattern.

Lookup APIs

tractor.find_actor(name, registry_addrs=None, enable_transports=['tcp'], only_first=True, raise_on_none=False)

Ask the registrar to find actor(s) by name.

Returns a connected portal to the last registered matching actor known to the registrar.

Parameters:

• name (str)

• registry_addrs (list[tuple[str, int | str]] | None)

• enable_transports (list[str])

• only_first (bool)

• raise_on_none (bool)

Return type:

AsyncGenerator[Portal | list[Portal] | None, None]

tractor.wait_for_actor(name, registry_addr=None)

Wait on at least one peer actor to register name with the registrar, yield a Portal to the first registree.

Parameters:

• name (str)

• registry_addr (tuple[str, int | str] | None)

Return type:

AsyncGenerator[Portal, None]

tractor.query_actor(name, regaddr=None)

Lookup a transport address (by actor name) via querying a registrar listening @ regaddr.

Yields a tuple of (addr, reg_portal) where,

• addr is the transport protocol (socket) address or None if no entry under that name exists,

• reg_portal is the Portal (or LocalPortal when the current actor is the registrar) used for the lookup (or None when the peer was found locally via get_peer_by_name()).

Parameters:

• name (str)

• regaddr (tuple[str, int | str] | None)

Return type:

AsyncGenerator[tuple[tuple[str, int | str] | None, Portal | LocalPortal | None], None]

tractor.get_registry(addr=None)

Return a portal instance connected to a local or remote registry-service actor; if a connection already exists re-use it (presumably to call a .register_actor() registry runtime RPC ep).

Parameters:

addr (tuple[str, int | str] | None)

Return type:

AsyncGenerator[Portal | LocalPortal | None, None]

Note

find_actor() yields None when nothing is registered under the name (or raises with raise_on_none=True); wait_for_actor() blocks until the name appears; query_actor() only looks up the address without connecting to the target.

The Registrar

class tractor.Registrar(*args, **kwargs)

Bases: Actor

A special registrar Actor who can contact all other actors within its immediate process tree and keeps a registry of others meant to be discoverable in a distributed application.

Normally the registrar is also the “root actor” and thus always has access to the top-most-level actor (process) nursery.

By default, the registrar is always initialized when and if no other registrar socket addrs have been specified to runtime init entry-points (such as open_root_actor() or open_nursery()). Any time a new main process is launched (and thus a new root actor created) and, no existing registrar can be contacted at the provided registry_addr, then a new one is always created; however, if one can be reached it is used.

Normally a distributed app requires at least one registrar per logical host where for that given “host space” (aka localhost IPC domain of addresses) it is responsible for making all other host (local address) bound actors discoverable to external actor trees running on remote hosts.

A Registrar is just an Actor subtype maintaining the name -> addresses table; you rarely touch it directly beyond passing registry_addrs / ensure_registry=True to open_root_actor(). Check Actor.is_registrar to ask “am I it?”.

Legacy Arbiter alias

Deprecated since version 0.1.0a6: tractor.Arbiter survives only as a class alias of Registrar and all “arbiter” terminology is replaced by “registrar”/”registry” across the API: get_arbiter() is removed (use get_registry()) and the arbiter_addr kwarg is replaced by registry_addrs.

See also

Runtime and spawning for booting a registrar via open_root_actor(registry_addrs=...), IPC and logging for the transport/address model the registry stores, and Actor discovery for the worked walkthrough.