View Source Enfiladex (enfiladex v0.3.1)

Enfiladex is the drop-in Common Test wrapper for ExUnit. It also exposes functions to run some code on a freshly started remote node(s).

All one needs to evaluate the code on one or more of connected nodes, would be to call a function exported from this module.

Known config parameters:

transfer_config (default: true) — whether the configuration of application(s) should be transferred to the started nodes, accepts boolean() | atom() where atom() is the application name besides already loaded the config is to be transferred for, normally it’s the main application configuration
start_applications (default: true) — boolean() | atom() specifying whether the application(s) should have been starter on the spawned node(s)
nodes (default: 3) — for multi_peer/3, the number of nodes to start

Due to sophisticated way of how Elixir compiler loads paths, _Erlang_’s common_test is not available by default, which might result in compilation errors. Add this to project section in your mix.exs to make it work:

prune_code_paths: Mix.env() == :prod

To use functions from this module with ExUnit tests, one needs a named node. Either run mix test in a named environment, or use mix enfiladex.ex_unit task. Make sure epmd (of any service providing distribution) is started in the target environment.

Allowed start options besides ones above: https://www.erlang.org/doc/man/peer#type-start_options

More rpc functions which might be used: https://www.erlang.org/doc/man/rpc

Summary

Types

callback()

The callback to be called on the result on the remote node(s)

callback_return_value()

The return value of the callback function executed from remote peer

callee()

The function to be passed for execution on the remote node(s)

callee_return_value()

The return value of the function executed on remote peer

peer()

The peer handler

started_peer()

The result of starting a peer as returned by erlang

Functions

block_call_everywhere(mod, fun, args)

Calls the function on all the nodes, visible to this node.

call_everywhere(mod, fun, args)

Calls the function on all the nodes, visible to this node.

multi_peer(fun, callback \\ [], config \\ [])

Executes the function given as first argument on several newly spawned nodes, with options passed as config argument.

peer(fun, callback \\ [], config \\ [])

Executes the function given as first argument on the newly spawned node, with options passed as config argument.

rpc_block_call(nodes, arg)

Calls the function passed as mfa/0 on remote nodes passed as the first argument.

rpc_call(nodes, arg)

Calls the function passed as mfa/0 on remote nodes passed as the first argument.

start_peers(nodes \\ 3, config \\ [])

Starts the requested amount of peers. These peers should be then stopped with stop_peers/1.

stop_peers(peers)

Stops the peers previously started with start_peers/1.

Types

callback()

@type callback() ::
  (callee_return_value() -> callback_return_value())
  | (node(), callee_return_value() -> callback_return_value())
  | (:peer.server_ref(), node(), callee_return_value() ->
       callback_return_value())

The callback to be called on the result on the remote node(s)

callback_return_value()

@type callback_return_value() :: any()

The return value of the callback function executed from remote peer

callee()

@type callee() ::
  {module(), atom(), [term()]}
  | (-> callee_return_value())
  | (node() -> callee_return_value())
  | (:peer.server_ref(), node() -> callee_return_value())

The function to be passed for execution on the remote node(s)

callee_return_value()

@type callee_return_value() :: any()

The return value of the function executed on remote peer

peer()

@type peer() :: pid()

The peer handler

started_peer()

@type started_peer() :: {:ok, peer()} | {:ok, peer(), node()} | {:error, any()}

The result of starting a peer as returned by erlang

Functions

block_call_everywhere(mod, fun, args)

@spec block_call_everywhere(module(), atom(), [term()]) :: [result] when result: any()

Calls the function on all the nodes, visible to this node.

Use Enfiladex.rpc_block_call/2 to call the function on selected nodes (e. g. on all the connected nodes,) as rpc_block_call([node() | Node.list(:connected)], {mod, fun, args}).

See node types for more info.

call_everywhere(mod, fun, args)

@spec call_everywhere(module(), atom(), [term()]) :: [result] when result: any()

Calls the function on all the nodes, visible to this node.

Use Enfiladex.rpc_call/2 to call the function on selected nodes (e. g. on all the connected nodes,) as rpc_call([node() | Node.list(:connected)], {mod, fun, args}).

See node types for more info.

multi_peer(fun, callback \\ [], config \\ [])

@spec multi_peer(callee(), callback() | keyword(), keyword()) :: [
  callee_return_value()
]

Executes the function given as first argument on several newly spawned nodes, with options passed as config argument.

It would call Callback(Result) for each result on each node, if callback was passed, before stopping the peer. The order is not guaranteed.

peer(fun, callback \\ [], config \\ [])

@spec peer(callee(), callback() | keyword(), keyword()) :: callee_return_value()

Executes the function given as first argument on the newly spawned node, with options passed as config argument.

It would call Callback(Result) if callback passed before stopping the peer.

Examples

iex> {_, _, result} = Enfiladex.peer({IO, :inspect, [:ok]})
...> result
:ok

rpc_block_call(nodes, arg)

@spec rpc_block_call(node() | [node()], {module(), atom(), [term()]}) :: [result]
when result: any()

Calls the function passed as mfa/0 on remote nodes passed as the first argument.

Uses :rpc.block_call/4 for non-blocking cross-node call.

rpc_call(nodes, arg)

@spec rpc_call(node() | [node()], {module(), atom(), [term()]}) :: [result]
when result: any()

Calls the function passed as mfa/0 on remote nodes passed as the first argument.

Uses :rpc.call/4 for non-blocking cross-node call.

start_peers(nodes \\ 3, config \\ [])

@spec start_peers(
  pos_integer(),
  keyword()
) :: {[started_peer()], [{peer(), node()}]}

Starts the requested amount of peers. These peers should be then stopped with stop_peers/1.

stop_peers(peers)

@spec stop_peers(
  started_peer()
  | [started_peer()]
  | {[started_peer()], [{peer(), node()}]}
) :: [:ok]

Stops the peers previously started with start_peers/1.