distribute/registry

Types

Pid

Re-export Pid from gleam/erlang/process for API compatibility. Use gleam/erlang/process.Pid directly in new code.

pub type Pid =
  process.Pid

RegisterError

</>

pub type RegisterError {
  AlreadyRegistered
  InvalidProcess
  InvalidName(String)
  NetworkError(String)
  RegisterFailed(String)
}

Constructors

```
AlreadyRegistered
```
Name is already registered by another process.
```
InvalidProcess
```
Process is not alive or invalid.
```
InvalidName(String)
```
Name contains invalid characters or is too long.
```
NetworkError(String)
```
Network partition or connectivity issue.
```
RegisterFailed(String)
```
Generic registration failure.

Values

register

</>

pub fn register(
  name: String,
  pid: process.Pid,
) -> Result(Nil, RegisterError)

register_subject

</>

pub fn register_subject(
  name: String,
  subject: process.Subject(a),
) -> Result(Nil, RegisterError)

Deprecated: Use register_typed instead

register_typed

</>

pub fn register_typed(
  name: String,
  subject: process.Subject(msg),
) -> Result(Nil, RegisterError)

This registers the owner Pid of the subject.

Recommended: Use global.GlobalSubject and register it with this function. The GlobalSubject pattern ensures type-safe messaging with encoder/decoder.

For GlobalSubject: Create with global.new(encoder, decoder), then register with register_typed(name, global.subject(global_subject)).

For custom Subject: Works but requires clients to know the message format.

unregister

</>

pub fn unregister(name: String) -> Result(Nil, RegisterError)

Unregister a globally registered name.

whereis

</>

pub fn whereis(name: String) -> Result(process.Pid, Nil)

Look up a globally registered process by name. Returns Ok(pid) if found, Error(Nil) otherwise.

whereis_global

</>

pub fn whereis_global(
  name: String,
  encoder: fn(msg) -> Result(BitArray, codec.EncodeError),
  decoder: fn(BitArray) -> Result(msg, codec.DecodeError),
) -> Result(global.GlobalSubject(msg), Nil)

Look up a globally registered GlobalSubject (RECOMMENDED).

This is the type-safe way to lookup distributed processes. Returns a GlobalSubject that enforces encoder/decoder usage.

On success, returns a GlobalSubject that can send/receive typed messages. On error, returns Error(Nil) if the name is not registered.

whereis_typed

</>

pub fn whereis_typed(
  name: String,
) -> Result(process.Subject(msg), Nil)

Deprecated: Use whereis_global for GlobalSubject or whereis_with_tag for custom actors

Look up a globally registered process and return a typed Subject with Nil tag.

⚠️ DEPRECATED: Use whereis_global for GlobalSubject or whereis_with_tag for standard actors where you know the tag.

The returned Subject has a Nil tag and won’t work with standard gleam_otp actors.

whereis_with_tag

</>

pub fn whereis_with_tag(
  name: String,
  tag: dynamic.Dynamic,
) -> Result(process.Subject(msg), Nil)

Look up a globally registered process with explicit tag.

Use this when you know the tag of the remote process (e.g., for custom actors). For GlobalSubject, use whereis_global instead (recommended).

The tag parameter should match the tag used by the remote actor. For most cases with Nil tags, use dynamic.nil() as the tag.