barnacle

Types

Barnacle

opaque </>

The entrypoint for creating a barnacle. Generic over the error returned by strategy-specific functions.

pub opaque type Barnacle(error)

BarnacleResponse

</>

A response from a barnacle actor. This will be sent to the listener subject.

pub type BarnacleResponse(error) {
  RefreshResponse(RefreshResult(error))
  PauseResponse(Nil)
  ShutdownResponse(Nil)
}

Constructors

```
RefreshResponse(RefreshResult(error))
```
```
PauseResponse(Nil)
```
```
ShutdownResponse(Nil)
```

Message

opaque </>

A message that can be sent to a barnacle actor.

pub opaque type Message(error)

NodeDisconnectError

</>

An error that can occur when disconnecting from a node.

pub type NodeDisconnectError {
  FailedToDisconnect
  LocalNodeIsNotAlive
}

Constructors

```
FailedToDisconnect
```
```
LocalNodeIsNotAlive
```

RefreshError

</>

The error type for a barnacle refresh.

pub type RefreshError(error) {
  StrategyError(error)
  ConnectError(List(#(atom.Atom, node.ConnectError)))
  DisconnectError(List(#(atom.Atom, NodeDisconnectError)))
}

Constructors

```
StrategyError(error)
```

ConnectError(List(#(atom.Atom, node.ConnectError)))

DisconnectError(List(#(atom.Atom, NodeDisconnectError)))

RefreshResult

</>

The result of a barnacle refresh.

pub type RefreshResult(error) =
  Result(List(atom.Atom), RefreshError(error))

Strategy

opaque </>

A custom strategy for discovering and connecting to nodes.

pub opaque type Strategy(error)

Functions

child_spec

</>

pub fn child_spec(
  barnacle: Barnacle(a),
  parent: Subject(Subject(Message(a))),
) -> ChildSpec(Message(a), b, b)

Create a child spec for your barnacle for use in a supervision tree.

custom

</>

pub fn custom(strategy: Strategy(a)) -> Barnacle(a)

Create a barnacle with a custom strategy. This requires at least one function to discover nodes.

You can also supply your own functions for connecting, disconnecting, and listing nodes. If these are not supplied, the default Distributed Erlang functions will be used.

Barnacles are generic over their error type, known as the strategy error. Your strategy functions may use this to return custom errors.

dns

</>

pub fn dns(
  basename: String,
  hostname_query: String,
) -> Barnacle(Nil)

Create a barnacle that discovers nodes using DNS. The first argument is the basename of the nodes. Currently, Barnacle only supports connecting to nodes with the same basename.

The second argument is the hostname to query against. Both A and AAAA records will be queried.

epmd

</>

pub fn epmd(nodes: List(Atom)) -> Barnacle(Nil)

Create a barnacle that connects to a known list of nodes. These may be remote nodes, or nodes on the same hostname as the current node.

get_node_basename

</>

pub fn get_node_basename(node: Node) -> Result(String, Nil)

Get the basename of a node.

Useful for getting the basename of the current node for use with the DNS strategy.

Example:

import barnacle
import gleam/erlang/node

pub fn main() {
  let assert Ok(basename) = barnacle.get_node_basename(node.self())
}

local_epmd

</>

pub fn local_epmd() -> Barnacle(Nil)

Create a barnacle that uses the local EPMD to discover nodes. This will discover nodes on the same hostname as the current node.

new_strategy

</>

pub fn new_strategy(
  discover_nodes: fn() -> Result(List(Atom), a),
) -> Strategy(a)

Create a new custom strategy with a single function to discover nodes.

pause

</>

pub fn pause(subject: Subject(Message(a)), timeout: Int) -> Nil

Pause a barnacle actor. Sending a refresh will restart the actor.

refresh

</>

pub fn refresh(
  subject: Subject(Message(a)),
  timeout: Int,
) -> Result(List(Atom), RefreshError(a))

Refresh a barnacle actor. This will attempt to connect to new nodes, and disconnect from nodes that are no longer available.

This will reset the poll timer.

run_once

</>

pub fn run_once(
  barnacle: Barnacle(a),
) -> Result(List(Atom), RefreshError(a))

Run the refresh function once only. This will not start the actor, and will not do any polling.

In this case, most configuration options are irrelevant and will be ignored.

shutdown

</>

pub fn shutdown(
  subject: Subject(Message(a)),
  timeout: Int,
) -> Nil

Shutdown a barnacle actor. This will stop the actor, and stop any future refreshes.

start

</>

pub fn start(
  barnacle: Barnacle(a),
) -> Result(Subject(Message(a)), StartError)

Start a barnacle actor. This will start the actor, and begin polling for nodes.

with_connect_nodes_function

</>

pub fn with_connect_nodes_function(
  strategy: Strategy(a),
  connect_nodes: fn(List(Atom)) ->
    Result(List(Atom), List(#(Atom, ConnectError))),
) -> Strategy(a)

Add a custom node connection function to your strategy. Useful if you want to use an alternative to Distributed Erlang, such as Partisan.

with_disconnect_nodes_function

</>

pub fn with_disconnect_nodes_function(
  strategy: Strategy(a),
  disconnect_nodes: fn(List(Atom)) ->
    Result(List(Atom), List(#(Atom, NodeDisconnectError))),
) -> Strategy(a)

Add a custom node disconnection function to your strategy. Useful if you want to use an alternative to Distributed Erlang, such as Partisan.

with_list_nodes_function

</>

pub fn with_list_nodes_function(
  strategy: Strategy(a),
  list_nodes: fn() -> Result(List(Atom), a),
) -> Strategy(a)

Add a custom node listing function to your strategy. Useful if you want to use an alternative to Distributed Erlang, such as Partisan.

with_listener

</>

pub fn with_listener(
  barnacle: Barnacle(a),
  listener: Subject(BarnacleResponse(a)),
) -> Barnacle(a)

Set the listener subject for your barnacle. This will be notified whenever the barnacle refreshes, is paused, or is shutdown.

with_name

</>

pub fn with_name(
  barnacle: Barnacle(a),
  name: String,
) -> Barnacle(a)

Give the barnacle actor process a custom name.

with_poll_interval

</>

pub fn with_poll_interval(
  barnacle: Barnacle(a),
  poll_interval: Int,
) -> Barnacle(a)

Set the poll interval for the barnacle actor. Defaults to 5000ms.