SwimEx (SwimEx v0.1.0)

View Source

SWIM+INF+Susp cluster membership protocol.

Quick start

children = [
  {SwimEx.Supervisor, host: "10.0.0.1", port: 7771,
                      seeds: [{"10.0.0.2", 7771}]}
]
Supervisor.start_link(children, strategy: :one_for_one)

SwimEx.subscribe()
SwimEx.members()

Membership events

After calling subscribe/1, the calling process receives messages of the form:

{:swim, event, node_id}

where event is one of:

  • :node_up — a node became (or was confirmed) alive
  • :node_suspect — a node is suspected dead
  • :node_down — a node is confirmed dead

and node_id is {host, port, cookie}.

Summary

Functions

leave(name \\ :swim)

Broadcasts a "dead" status for the local node, then stops the Protocol process.

members(name \\ :swim, opts \\ [])

Returns current cluster members (alive + suspect by default).

subscribe(name \\ :swim)

Subscribes the calling process to membership events.

unsubscribe(name \\ :swim)

Unsubscribes the calling process from membership events.

Functions

leave(name \\ :swim)

@spec leave(atom()) :: :ok

Broadcasts a "dead" status for the local node, then stops the Protocol process.

Call this before stopping the application for a graceful shutdown that immediately informs peers. The supervisor will restart the process afterward; stop the application (or the SwimEx supervisor) separately to prevent the restart.

Parameters

  • name: (optional) The registered name of the SwimEx instance. Defaults to :swim.

Returns

  • :ok

members(name \\ :swim, opts \\ [])

@spec members(
  atom(),
  keyword()
) :: [
  {String.t(), :inet.port_number(), String.t(), SwimEx.Membership.status(),
   non_neg_integer()}
]

Returns current cluster members (alive + suspect by default).

Parameters

  • name: (optional) The registered name of the SwimEx instance. Defaults to :swim.
  • opts: (optional) A keyword list of options.
    • :include_dead: Boolean. If true, includes nodes marked as dead. Defaults to false.

Returns

  • A list of members, where each member is a tuple: {host, port, cookie, status, incarnation}.

subscribe(name \\ :swim)

@spec subscribe(atom()) :: :ok

Subscribes the calling process to membership events.

The caller receives messages of the form {:swim, event, node_id} where event is :node_up, :node_suspect, or :node_down, and node_id is {host, port, cookie}. See the module doc for details.

Parameters

  • name: (optional) The registered name of the SwimEx instance. Defaults to :swim.

Returns

  • :ok

unsubscribe(name \\ :swim)

@spec unsubscribe(atom()) :: :ok

Unsubscribes the calling process from membership events.

Parameters

  • name: (optional) The registered name of the SwimEx instance. Defaults to :swim.

Returns

  • :ok