Node — Elixir v1.16.3

Search documentation of Elixir

# View Source Node (Elixir v1.16.3)

Functions related to VM nodes.

Some of the functions in this module are inlined by the compiler, similar to functions in the `Kernel` module and they are explicitly marked in their docs as "inlined by the compiler". For more information about inlined functions, check out the `Kernel` module.

# Summary

## Types

state()
t()

## Functions

alive?()

Returns `true` if the local node is alive.

connect(node)

Establishes a connection to `node`.

disconnect(node)

Forces the disconnection of a node.

get_cookie()

Returns the magic cookie of the local node.

list()

Returns a list of all visible nodes in the system, excluding the local node.

list(args)

Returns a list of nodes according to argument given.

monitor(node, flag)

Monitors the status of the node.

monitor(node, flag, options)

Behaves as `monitor/2` except that it allows an extra option to be given, namely `:allow_passive_connect`.

ping(node)

Tries to set up a connection to node.

self()

Returns the current node.

set_cookie(node \\ Node.self(), cookie)

Sets the magic cookie of `node` to the atom `cookie`.

spawn(node, fun)

Returns the PID of a new process started by the application of `fun` on `node`. If `node` does not exist, a useless PID is returned.

spawn(node, fun, opts)

Returns the PID of a new process started by the application of `fun` on `node`.

spawn(node, module, fun, args)

Returns the PID of a new process started by the application of `module.function(args)` on `node`.

spawn(node, module, fun, args, opts)

Returns the PID of a new process started by the application of `module.function(args)` on `node`.

spawn_link(node, fun)

Returns the PID of a new linked process started by the application of `fun` on `node`.

spawn_link(node, module, fun, args)

Returns the PID of a new linked process started by the application of `module.function(args)` on `node`.

spawn_monitor(node, fun)

Spawns the given function on a node, monitors it and returns its PID and monitoring reference.

spawn_monitor(node, module, fun, args)

Spawns the given module and function passing the given args on a node, monitors it and returns its PID and monitoring reference.

start(name, type \\ :longnames, tick_time \\ 15000)

Turns a non-distributed node into a distributed node.

stop()

Turns a distributed node into a non-distributed node.

# Types

Link to this type

# state()

View Source

    @type state() :: :visible | :hidden | :connected | :this | :known

Link to this type

# t()

View Source

    @type t() :: node()

# Functions

Link to this function

# alive?()

View Source

    @spec alive?() :: boolean()

Returns `true` if the local node is alive.

That is, if the node can be part of a distributed system.

Link to this function

# connect(node)

View Source

    @spec connect(t()) :: boolean() | :ignored

Establishes a connection to `node`.

Returns `true` if successful, `false` if not, and the atom `:ignored` if the local node is not alive.

For more information, see `:net_kernel.connect_node/1`.

Link to this function

# disconnect(node)

View Source

    @spec disconnect(t()) :: boolean() | :ignored

Forces the disconnection of a node.

This will appear to the `node` as if the local node has crashed. This function is mainly used in the Erlang network authentication protocols. Returns `true` if disconnection succeeds, otherwise `false`. If the local node is not alive, the function returns `:ignored`.

For more information, see `:erlang.disconnect_node/1`.

Link to this function

# get_cookie()

View Source

    @spec get_cookie() :: atom()

Returns the magic cookie of the local node.

Returns the cookie if the node is alive, otherwise `:nocookie`.

Link to this function

# list()

View Source

    @spec list() :: [t()]

Returns a list of all visible nodes in the system, excluding the local node.

Same as `list(:visible)`.

Inlined by the compiler.

Link to this function

# list(args)

View Source

    @spec list(state() | [state()]) :: [t()]

Returns a list of nodes according to argument given.

The result returned when the argument is a list, is the list of nodes satisfying the disjunction(s) of the list elements.

For more information, see `:erlang.nodes/1`.

Inlined by the compiler.

Link to this function

# monitor(node, flag)

View Source

    @spec monitor(t(), boolean()) :: true

Monitors the status of the node.

If `flag` is `true`, monitoring is turned on. If `flag` is `false`, monitoring is turned off.

For more information, see `:erlang.monitor_node/2`.

For monitoring status changes of all nodes, see `:net_kernel.monitor_nodes/2`.

Link to this function

# monitor(node, flag, options)

View Source

    @spec monitor(t(), boolean(), [:allow_passive_connect]) :: true

Behaves as `monitor/2` except that it allows an extra option to be given, namely `:allow_passive_connect`.

For more information, see `:erlang.monitor_node/3`.

For monitoring status changes of all nodes, see `:net_kernel.monitor_nodes/2`.

Link to this function

# ping(node)

View Source

    @spec ping(t()) :: :pong | :pang

Tries to set up a connection to node.

Returns `:pang` if it fails, or `:pong` if it is successful.

## Examples

    iex> Node.ping(:unknown_node)
    :pang

Link to this function

# self()

View Source

    @spec self() :: t()

Returns the current node.

It returns the same as the built-in `node()`.

Link to this function

# set_cookie(node \\ Node.self(), cookie)

View Source

    @spec set_cookie(t(), atom()) :: true

Sets the magic cookie of `node` to the atom `cookie`.

The default node is `Node.self/0`, the local node. If `node` is the local node, the function also sets the cookie of all other unknown nodes to `cookie`.

This function will raise `FunctionClauseError` if the given `node` is not alive.

Link to this function

# spawn(node, fun)

View Source

    @spec spawn(t(), (-> any())) :: pid()

Returns the PID of a new process started by the application of `fun` on `node`. If `node` does not exist, a useless PID is returned.

For the list of available options, see `:erlang.spawn/2`.

Inlined by the compiler.

Link to this function

# spawn(node, fun, opts)

View Source

    @spec spawn(t(), (-> any()), Process.spawn_opts()) :: pid() | {pid(), reference()}

Returns the PID of a new process started by the application of `fun` on `node`.

If `node` does not exist, a useless PID is returned.

For the list of available options, see `:erlang.spawn_opt/3`.

Inlined by the compiler.

Link to this function

# spawn(node, module, fun, args)

View Source

    @spec spawn(t(), module(), atom(), [any()]) :: pid()

Returns the PID of a new process started by the application of `module.function(args)` on `node`.

If `node` does not exist, a useless PID is returned.

For the list of available options, see `:erlang.spawn/4`.

Inlined by the compiler.

Link to this function

# spawn(node, module, fun, args, opts)

View Source

    @spec spawn(t(), module(), atom(), [any()], Process.spawn_opts()) ::
      pid() | {pid(), reference()}

Returns the PID of a new process started by the application of `module.function(args)` on `node`.

If `node` does not exist, a useless PID is returned.

For the list of available options, see `:erlang.spawn/4`.

Inlined by the compiler.

Link to this function

# spawn_link(node, fun)

View Source

    @spec spawn_link(t(), (-> any())) :: pid()

Returns the PID of a new linked process started by the application of `fun` on `node`.

A link is created between the calling process and the new process, atomically. If `node` does not exist, a useless PID is returned (and due to the link, an exit signal with exit reason `:noconnection` will be received).

Inlined by the compiler.

Link to this function

# spawn_link(node, module, fun, args)

View Source

    @spec spawn_link(t(), module(), atom(), [any()]) :: pid()

Returns the PID of a new linked process started by the application of `module.function(args)` on `node`.

A link is created between the calling process and the new process, atomically. If `node` does not exist, a useless PID is returned (and due to the link, an exit signal with exit reason `:noconnection` will be received).

Inlined by the compiler.

Link to this function

# spawn_monitor(node, fun)

View Source (since 1.14.0)

    @spec spawn_monitor(t(), (-> any())) :: {pid(), reference()}

Spawns the given function on a node, monitors it and returns its PID and monitoring reference.

Inlined by the compiler.

Link to this function

# spawn_monitor(node, module, fun, args)

View Source (since 1.14.0)

    @spec spawn_monitor(t(), module(), atom(), [any()]) :: {pid(), reference()}

Spawns the given module and function passing the given args on a node, monitors it and returns its PID and monitoring reference.

Inlined by the compiler.

Link to this function

# start(name, type \\ :longnames, tick_time \\ 15000)

View Source

    @spec start(node(), :longnames | :shortnames, non_neg_integer()) ::
      {:ok, pid()} | {:error, term()}

Turns a non-distributed node into a distributed node.

This functionality starts the `:net_kernel` and other related processes.

This function is rarely invoked in practice. Instead, nodes are named and started via the command line by using the `--sname` and `--name` flags. If you need to use this function to dynamically name a node, please make sure the `epmd` operating system process is running by calling `epmd -daemon`.

Invoking this function when the distribution has already been started, either via the command line interface or dynamically, will return an error.

## Examples

    {:ok, pid} = Node.start(:example, :shortnames, 15000)

Link to this function

# stop()

View Source

    @spec stop() :: :ok | {:error, :not_allowed | :not_found}

Turns a distributed node into a non-distributed node.

For other nodes in the network, this is the same as the node going down. Only possible when the node was started with `Node.start/3`, otherwise returns `{:error, :not_allowed}`. Returns `{:error, :not_found}` if the local node is not alive.