distribute/config

Types

Config

pub type Config {
  Config(
    default_call_timeout_ms: Int,
    default_init_timeout_ms: Int,
    max_payload_size_bytes: Int,
    max_distribution_atoms: Int,
    max_decoded_list_elements: Int,
    isolated_proxy_shutdown_grace_ms: Int,
    resource_owner_poll_ms: Int,
    health_proxy_shutdown_grace_ms: Int,
    conflict_resolver_timeout_ms: Int,
  )
}

Constructors

```
Config(
  default_call_timeout_ms: Int,
  default_init_timeout_ms: Int,
  max_payload_size_bytes: Int,
  max_distribution_atoms: Int,
  max_decoded_list_elements: Int,
  isolated_proxy_shutdown_grace_ms: Int,
  resource_owner_poll_ms: Int,
  health_proxy_shutdown_grace_ms: Int,
  conflict_resolver_timeout_ms: Int,
)
```
Arguments

default_call_timeout_ms

Timeout for global.call requests, in milliseconds.

default_init_timeout_ms

Timeout for OTP actor initialisation, in milliseconds.

max_payload_size_bytes

Maximum allowed payload size in bytes. global.send, global.call and global.receive return PayloadTooLarge when a message exceeds this limit.

max_distribution_atoms

Maximum number of fresh atoms distribute will create through its FFI helpers (node names + cookies). Existing atoms cost nothing. Once the budget is exhausted, cluster.connect, cluster.ping, and cluster.start_node return AtomBudgetExceeded instead of letting the caller exhaust the VM atom table (default cap 1 048 576, no GC).

Default 10 000. Ten times a generous cluster size, four orders of magnitude below the VM cap.

max_decoded_list_elements

Decoder cap for list element count. Protects against CPU and heap amplification from tiny payloads with huge declared counts (for example <<1_000_000:32>> with list(nil())).

Default 10 000. Raise only if your workload really needs larger in-memory frames and you have tested scheduler impact.

isolated_proxy_shutdown_grace_ms

Grace window while waiting for proxy DOWN in call_isolated timeout teardown.

Default 5 000 ms.

resource_owner_poll_ms

Poll interval used by actor.start_resource_owner fallback liveness checks when DOWN delivery is delayed.

Default 5 000 ms.

health_proxy_shutdown_grace_ms

Grace window while waiting for proxy DOWN in cluster.health timeout teardown.

Default 1 000 ms.

conflict_resolver_timeout_ms

Hard deadline (ms) for a custom split-brain conflict resolver installed via registry.register_global_with_resolver/3.

The resolver runs inside the global_name_server worker; while it executes, every :global operation cluster-wide is serialised behind it. Past this deadline the FFI shim kills the worker and applies a deterministic fallback (lowest term-ordered PID wins). Lower is safer for cluster throughput; higher gives the user fn room to do RPC work.

Default 1 000 ms. Pure resolvers (lowest_pid_wins, keep_local, node_priority) take microseconds and never approach this. RPC-based resolvers should fit comfortably inside 1 second on a healthy cluster; raise only when profiling shows a legitimate need and the cluster can tolerate the longer per-conflict stall.

ConfigError

</>

pub type ConfigError {
  AlreadyConfigured
  InvalidTimeout(field: String, value: Int)
  InvalidPayloadSize(Int)
  InvalidAtomBudget(Int)
  InvalidListElementCap(Int)
}

Constructors

```
AlreadyConfigured
```
The configuration was already loaded and cannot be mutated.

InvalidTimeout(field: String, value: Int)

A timeout field was zero or negative.

```
InvalidPayloadSize(Int)
```
The payload size limit was zero or negative.
```
InvalidAtomBudget(Int)
```
The atom-creation budget was zero or negative.
```
InvalidListElementCap(Int)
```
The list decode element cap was zero or negative.

Values

config_error_to_string

</>

pub fn config_error_to_string(err: ConfigError) -> String

configure

</>

pub fn configure(cfg: Config) -> Result(Nil, ConfigError)

Store a custom configuration. Call once at startup.

Returns Error(ConfigError) if any value is invalid (zero or negative) or if the configuration has already been loaded via a previous call.

Danger: call this only during application boot. persistent_term writes trigger a global VM-wide heap invalidation pass; exposing this path to runtime traffic is an operational footgun and can cause heartbeat failures between nodes under load.

Side-effect: also writes max_distribution_atoms to a separate persistent_term slot read by the FFI atom helpers, so the budget is observable from Erlang without needing to decode the Gleam Config tuple.

default

</>

pub fn default() -> Config

Returns the built-in defaults:

default_call_timeout_ms: 5 000 ms
default_init_timeout_ms: 5 000 ms
max_payload_size_bytes: 4 MiB (4 * 1 024 * 1 024)
max_distribution_atoms: 10 000
max_decoded_list_elements: 10 000
isolated_proxy_shutdown_grace_ms: 5 000 ms
resource_owner_poll_ms: 5 000 ms
health_proxy_shutdown_grace_ms: 1 000 ms
conflict_resolver_timeout_ms: 1 000 ms

get

</>

pub fn get() -> Config

Read the active configuration.

Never fails: returns default() when configure/1 has not been called.

Constructors

Arguments

Constructors