-spec broadcast(any(), module()) -> ok.

Broadcasts a message originating from this node.

The message is delivered to every node at least once. Mod is responsible for handling the message on remote nodes and for supplying the related information the broadcast substrate needs, both locally and on other nodes. Mod must be loaded on every member of the cluster and implement the partisan_plumtree_broadcast_handler behaviour.

-spec cancel_timer(Ref :: reference()) -> ok | time() | false.

Equivalent to cancel_timer(Ref, []).

-spec cancel_timer(Ref :: reference(), Opts :: list()) -> ok | time() | false.

Cancels the timer Ref — the Partisan counterpart of erlang:cancel_timer/2.

Opts accepts {async, boolean()} and {info, boolean()} with the same meaning as in erlang:cancel_timer/2. Works for both native timers and the emulated timers send_after/4 creates for remote destinations.

-spec cast_message(ServerRef :: server_ref(), Msg :: message()) -> ok.

Casts message Msg to the process identified by ServerRef (a server_ref/0), returning ok. Delivery is asynchronous and best-effort.

-spec cast_message(ServerRef :: server_ref(), Msg :: message(), Opts :: forward_opts()) -> ok.

Casts message Msg to the process identified by ServerRef, honouring Opts (forward_opts/0). Delivery is asynchronous and best-effort.

-spec cast_message(Node :: node(), ServerRef :: server_ref(), Msg :: message(), Opts :: forward_opts()) ->
                      ok.

Casts message Msg to the process ServerRef on Node, honouring Opts (forward_opts/0). Delivery is asynchronous and best-effort.

-spec channel_opts(Channel :: channel()) -> channel_opts() | no_return().

Returns the options (channel_opts/0) of the channel named Channel. Fails with badarg if no such channel exists.

-spec default_channel() -> channel().

Returns the name of the default channel.

-spec demonitor(MonitorRef :: reference() | remote_reference()) -> true.

Removes the monitor identified by MonitorRef; equivalent to demonitor(Ref, []).

Unlike erlang:demonitor/1, it does not fail if MonitorRef refers to a monitor started by another process.

-spec demonitor(MonitorRef :: reference() | remote_reference(), OptionList :: [demonitor_opt()]) ->
                   boolean().

Removes the monitor identified by MonitorRef, with options — Partisan's counterpart of erlang:demonitor/2.

flush removes a pending DOWN for this monitor from the caller's mailbox; info makes the call return whether the monitor was still live when removed.

-spec disconnect_node(Node :: node()) -> boolean() | ignored.

Disconnects the local node from Node — the counterpart of erlang:disconnect_node/1.

If Node is the local node, the node leaves the cluster; otherwise it leaves the peer identified by Node. Returns true on success and false if Node is not a known peer.

-spec exit(Pid :: pid() | remote_pid(), Reason :: term()) -> true.

Sends an exit signal with reason Reason to the process identified by Pid (a local pid or a remote_pid/0) — the Partisan counterpart of erlang:exit/2. For a remote reference the signal is delivered on the owning node via partisan_rpc.

-spec forward_message(ServerRef :: server_ref(), Msg :: message()) ->
                         partisan_peer_service_manager:forward_result().

Forwards message Msg to the process identified by ServerRef (a server_ref/0).

Forwarding is best-effort. It returns {error, Reason} — it does not raise — when the message could not be handed to a connection, most commonly because there is no usable connection to the target node on the requested channel. See partisan_peer_service_manager:forward_result/0 for the reasons Partisan's own managers report.

-spec forward_message(ServerRef :: server_ref(), Msg :: message(), Opts :: forward_opts()) ->
                         partisan_peer_service_manager:forward_result().

Forwards message Msg to the process identified by ServerRef, honouring Opts (forward_opts/0).

Best-effort; see forward_message/2 on the return value.

-spec forward_message(Node :: node(),
                      ServerRef :: server_ref(),
                      Msg :: message(),
                      Opts :: forward_opts()) ->
                         partisan_peer_service_manager:forward_result().

Forwards message Msg to the process ServerRef on Node, honouring Opts (forward_opts/0).

Best-effort; see forward_message/2 on the return value.

-spec is_alive() -> boolean().

Returns true if the local node is alive — that is, the peer service manager is running and the node can take part in a cluster.

-spec is_connected(NodeOrSpec :: node_spec() | node()) -> boolean().

Returns true if this node currently has a connection to NodeOrSpec.

-spec is_connected(NodeOrSpec :: node_spec() | node(), Channel :: channel()) -> boolean().

Returns true if this node currently has a connection to NodeOrSpec on Channel.

-spec is_fully_connected(NodeOrSpec :: node_spec() | node()) -> boolean().

Returns true if every expected connection to NodeOrSpec is established — one per configured channel at its configured parallelism.

-spec is_local(Arg) -> Result
                  when
                      Arg :: pid() | port() | reference() | remote_pid() | remote_reference(),
                      Result :: boolean().

Returns true if Arg belongs to the local node.

Arg may be a pid, port or reference, or one of their remote forms (remote_pid/0, remote_reference/0).

-spec is_local_name(Arg :: atom() | remote_name()) -> boolean() | no_return().

Returns true if Arg refers to a name on the local node.

A plain atom is always a local name; a remote_name/0 is checked against the local node.

-spec is_local_name(Arg :: atom() | remote_name(), Name :: atom()) -> boolean() | no_return().

Returns true if Arg refers to the locally registered name Name.

-spec is_local_pid(Arg :: pid() | remote_pid()) -> boolean() | no_return().

Returns true if Arg (a pid or remote_pid/0) is a pid on the local node.

-spec is_local_pid(Arg :: pid() | remote_pid(), Pid :: pid()) -> boolean() | no_return().

Returns true if Arg refers to the local pid Pid.

-spec is_local_reference(Arg :: reference() | remote_reference()) -> boolean() | no_return().

Returns true if Arg (a reference or remote_reference/0) was created on the local node.

-spec is_local_reference(Arg :: reference() | remote_reference(), LocalRef :: reference()) ->
                            boolean() | no_return().

Returns true if Arg refers to the local reference LocalRef.

-spec is_pid(any()) -> boolean() | no_return().

Returns true if Arg is a local process identifier or a remote_pid/0, false otherwise.

-spec is_process_alive(pid() | remote_pid()) -> boolean() | no_return().

Returns true if the process identified by Arg (a local pid or a remote_pid/0) is alive, false otherwise. For a remote reference the check runs on the owning node via partisan_rpc.

-spec is_reference(reference() | remote_reference()) -> boolean() | no_return().

Returns true if Arg is a local reference or a remote_reference/0, false otherwise.

-spec is_self(Arg) -> Result when Arg :: pid() | remote_pid(), Result :: boolean().

Returns true if Arg (a pid or remote_pid/0) is the calling process.

-spec join(node_spec()) -> ok.

Adds a peer to the cluster; a shortcut for partisan_peer_service:join/1.

Drops the peer connections to Nodes (a node name or a list of them).

The membership protocol re-establishes them if the nodes are still members, so this forces a reconnect rather than removing a node from the cluster.

-spec leave() -> ok.

Removes the local node from the cluster; a shortcut for partisan_peer_service:leave/0.

-spec make_ref() -> remote_reference() | no_return().

Returns a fresh remote reference — the Partisan counterpart of erlang:make_ref/0.

Equivalent to partisan_remote_ref:from_term(erlang:make_ref()).

Monitors Term as a process; equivalent to monitor(process, Term).

Deprecated: use monitor/2 instead.

-spec monitor(process, pid() | atom() | {atom(), node()}) -> reference();
             (process, remote_pid() | remote_name()) -> remote_reference() | no_return();
             (port, port() | atom()) -> reference() | no_return();
             (time_offset, clock_service) -> reference() | no_return().

Sends a monitor request of type Type for the entity identified by Item; equivalent to monitor(Type, Item, []).

If the monitored entity does not exist, or later changes monitored state, the caller receives a {Tag, MonitorRef, Type, Object, Info} message. This is Partisan's counterpart of erlang:monitor/2.

Fails with notalive if the partisan_monitor server is not running.

-spec monitor(process, pid() | atom(), [monitor_opt()]) -> reference();
             (port, port() | atom(), [erlang:monitor_option()]) -> reference();
             (time_offset, clock_service, [erlang:monitor_option()]) -> reference();
             (process, {atom(), node()}, [monitor_opt()]) -> reference() | remote_reference();
             (process, remote_pid(), [monitor_opt()]) -> remote_reference();
             (process, remote_name(), [monitor_opt()]) -> remote_reference().

Sends a monitor request of type Type for the entity identified by Item, with options.

If the monitored entity does not exist, or later changes monitored state, the caller receives a {Tag, MonitorRef, Type, Object, Info} message. This differs from the message erlang:monitor/3 sends only when the monitored item is a remote process, in which case MonitorRef is a remote_reference/0 and Object is a remote_pid/0 or remote_name/0.

This is Partisan's counterpart of erlang:monitor/3 and differs from it only when monitoring a process; for a port or time_offset it calls erlang:monitor/3 directly. Unlike erlang:monitor/3, it does not support aliases.

Monitoring a process

Creates a monitor between the calling process and the process identified by Item — a local or remote pid, a registered-name atom, or a {RegisteredName, Node} tuple for a process registered on another node. A monitor by name resolves the name to a pid once, at creation; later changes to the registration do not affect the existing monitor.

Pass {channel, Channel} in Opts to bind the monitor to a channel: the eventual DOWN is then delivered on that channel, in order with other traffic on it (see the channel-ordering note in the module documentation).

Fails soft: if the partisan_monitor server is not running, the returned reference receives an immediate DOWN with reason notalive.

-spec monitor_node(node() | node_spec(), boolean()) -> boolean().

Turns node-status monitoring of Node on (Flag = true) or off (false); equivalent to monitor_node(Node, Flag, []). Node may be a node name or a node_spec/0.

Calling monitor_node(Node, true) repeatedly is not an error: each calling process gets one independent monitor, so a process that called it twice still receives a single {nodedown, Node} if Node goes down — this differs from erlang:monitor_node/2.

{nodedown, Node} is delivered if Node fails, does not exist, or is not connected. Under a membership strategy with a partial view you therefore cannot monitor nodes outside your view. Monitoring the caller's own node returns false.

-spec monitor_node(Node :: node(), Flag :: boolean(), Options :: [allow_passive_connect]) -> true.

Turns node-status monitoring of Node on or off, with options.

Behaves as monitor_node/2 — see there for the repeated-call, delivery and partial-view semantics. Options accepts allow_passive_connect, which applies only on the Erlang-distribution path (connect_disterl = true); with the default overlay transport the options are ignored.

-spec monitor_nodes(Flag :: boolean()) -> ok | error | {error, term()}.

Subscribes (Flag = true) or unsubscribes (false) the calling process to node-status change messages; equivalent to monitor_nodes(Flag, []).

-spec monitor_nodes(Flag :: boolean(), [monitor_nodes_opt()]) -> ok | error | {error, term()}.

Subscribes (Flag = true) or unsubscribes (false) the calling process to node-status change messages, with options.

While subscribed, the process receives a {nodeup, Node} message when a peer connects and a {nodedown, Node} message when one disconnects. Opts mirrors the net_kernel node-monitoring options and may also carry a channel selector.

-spec node() -> node().

Returns the name of the local node.

-spec node(pid() | port() | reference()) -> node();
          (partisan_remote_ref:t()) -> node() | no_return().

Returns the node on which Arg originates.

Arg may be a pid, port or reference, or a Partisan remote reference. For a remote reference the node is read from the reference; for a local pid, port or reference it is erlang:node(Arg), falling back to node/0 when Erlang distribution is disabled.

-spec node_spec() -> node_spec().

Returns the node specification (node_spec/0) of the local node.

This is the information another node needs in order to join this one (see partisan_peer_service:join/1). The values of the map's keys must be sorted so the peer service can compare specifications and keep the membership view free of duplicates — relevant when you build a specification by hand for a custom orchestration strategy. Erlang maps are already sorted, so the only field you must keep sorted yourself is listen_addrs, which is a list.

-spec node_spec(node()) -> {ok, node_spec()} | {error, Reason :: any()}.

Returns {ok, NodeSpec} for the node named Node, or {error, Reason}. Equivalent to node_spec(Node, #{}); see node_spec/2 for how the specification is resolved.

-spec node_spec(Node :: binary() | list() | node(), Opts :: #{rpc_timeout => timeout()}) ->
                   {ok, node_spec()} | {error, Reason :: any()}.

Returns {ok, NodeSpec} for the node named Node, or {error, Reason}.

If a Partisan connection to Node already exists, the cached specification used to establish that connection is returned. Otherwise — the case under a peer-to-peer topology — the specification is fetched from the remote node with partisan_rpc, which requires the forward_opts configuration to enable broadcast and transitive. Opts may set rpc_timeout (default 5000 ms).

-spec nodes() -> [node()].

Returns the peers connected to this node over Partisan; equivalent to nodes(visible) and the counterpart of erlang:nodes/0.

If connect_disterl is true (as in some test setups) this does not include Erlang-distribution nodes — use erlang:nodes/0 for those.

-spec nodes(Arg :: node_type() | [node_type()]) -> [node()].

Returns nodes of the given type — the counterpart of erlang:nodes/1. When Arg is a list, returns the nodes satisfying any of its elements.

The node types differ from Erlang as follows:

• hidden — always []; Partisan has no hidden nodes.
• this — the list containing node/0.
• known — the nodes known to partisan_peer_service (its partisan_peer_service:members/0), not the nodes of pids, ports and references located on this node.
• visible — as in Erlang.

-spec nodestring() -> binary().

Returns the name of the local node as a binary string.

-spec process_info(Arg :: pid() | remote_pid()) -> [tuple()] | undefined.

Returns information about the process Arg (a pid or remote_pid/0), or undefined — the counterpart of erlang:process_info/1.

-spec process_info(Arg :: pid() | remote_pid(), Item :: atom() | [atom()]) -> [tuple()] | undefined.

Returns the requested information Item (an item or a list of items) about the process Arg (a pid or remote_pid/0), or undefined — the counterpart of erlang:process_info/2.

-spec self() -> remote_pid().

Returns the remote-reference form of the calling process's pid.

Equivalent to partisan_remote_ref:from_term(self()). This is more expensive than erlang:self/0, so you may want to cache the result in your process state — see self/1, which can cache it in the process dictionary (and note the shell caveat described there).

-spec self(Opts :: [cache]) -> remote_pid().

Returns the remote-reference form of the calling process's pid, optionally caching it.

With Opts = [] this is equivalent to self/0. With Opts = [cache] the result is computed once and stored in the process dictionary, then returned from there on subsequent calls.

-spec send(Dest :: send_dst(), Msg :: message()) -> message().

Sends message Msg to the destination Dest and returns Msg. Equivalent to send(Dest, Msg, []).

Follows erlang:send/2: delivery is best-effort and the message is returned whether or not it could be delivered. An unreachable destination is not an error here — it is not one for erlang:send/2 either, where sending to a dead process or an unreachable node simply returns.

Use send/3 when you need to know: it reports {error, Reason} rather than discarding the outcome.

-spec send(Dest :: send_dst(), Msg :: message(), Opts :: forward_opts()) ->
              ok | nosuspend | noconnect | {error, Reason :: any()}.

Sends message Msg to the destination Dest.

When distributed Erlang is enabled (connect_disterl is true) the message is delivered with erlang:send/3. Otherwise it is forwarded over Partisan with forward_message/3, honouring Opts (forward_opts/0) — and then a failure to reach the target is reported as {error, Reason} rather than raised.

-spec send_after(Time :: time(), Destination :: send_after_dst(), Msg :: message()) ->
                    TRef :: reference().

Equivalent to send_after(Time, Dest, Msg, []).

-spec send_after(Time :: time(),
                 Destination :: send_after_dst(),
                 Message :: message(),
                 Opts :: send_after_opts()) ->
                    TRef :: reference().

The Partisan counterpart of erlang:send_after/4.

For a local destination it calls the native implementation. For a remote destination it spawns a process that holds the timer and accepts cancellation (via cancel_timer/1,2); this is less efficient than the native implementation.

-spec spawn(Node :: node(), Fun :: fun(() -> any())) -> remote_pid().

Spawns Fun on Node and returns a remote_pid/0 for the new process — the Partisan counterpart of erlang:spawn/2. A remote spawn is carried out with partisan_rpc.

-spec spawn(Node :: node(), Mod :: module(), Function :: atom(), Args :: [term()]) -> remote_pid().

Spawns Module:Function(Args) on Node and returns a remote_pid/0 for the new process — the Partisan counterpart of erlang:spawn/4. A remote spawn is carried out with partisan_rpc.

-spec spawn_monitor(Node :: node(), Fun :: fun(() -> any())) ->
                       {remote_pid(), remote_reference()} | {pid(), reference()}.

Spawns Fun on Node and monitors it, returning {Pid, MonitorRef} — the Partisan counterpart of erlang:spawn_monitor/2. See monitor/2 for the shape of the reference and the DOWN message.

-spec spawn_monitor(Node :: node(), Mod :: module(), Function :: atom(), Args :: [term()]) ->
                       {remote_pid(), remote_reference()} | {pid(), reference()}.

Spawns Module:Function(Args) on Node and monitors it, returning {Pid, MonitorRef} — the Partisan counterpart of erlang:spawn_monitor/4. See monitor/2 for the shape of the reference and the DOWN message.

Starts the partisan application and all of its dependencies.

Stops the partisan application.

-spec whereis(Arg :: atom() | remote_name()) -> pid() | port() | undefined.

Returns the pid or port registered under Arg, or undefined — the counterpart of erlang:whereis/1.

Arg is a local name (an atom) or a remote_name/0 for the local node. Fails with badarg if Arg is a remote name for another node.