partisan (partisan v5.0.2)

View Source

This module implements the Partisan API. Some of the functions in this module are the Partisan counterparts of a subset of the functions found in the erlang and net_kernel modules.

-----------------------------------------------------------------------------

Summary

Functions

Broadcasts a message originating from this node.

Cast message to a remote ref

Cast message to registered process on the remote side.

Cast message to registered process on the remote side.

Returns a channel with name Name. Fails if a channel named Name doesn't exist.

It differs from erlang:demonitor/1 in that it doesn't fail if MonitorRef refers to a monitoring started by another process.

Forward message to registered process on the remote side.

Forward message to registered process on the remote side.

Forward message to registered process on the remote side.

Returns true if the local node is alive (that is, if the node can be part of a distributed system), otherwise false.

Returns the name of the local node.

Returns the name of the local node.

Returns the name of the local node.

Returns the name of the local node.

Returns the name of the local node.

Returns the name of the local node.

Returns true if Arg is the caller's process identifier.

Returns a new partisan_remote_ref. This is the same as calling partisan_remote_ref:from_term(erlang:make_ref()).

monitor(Term) deprecated

Sends a monitor request of type Type to the entity identified by Item. If the monitored entity does not exist or it changes monitored state, the caller of monitor/2 is notified by a message on the following format: {Tag, MonitorRef, Type, Object, Info}

Sends a monitor request of type Type to the entity identified by Item. If the monitored entity does not exist or it changes monitored state, the caller of monitor/2 is notified by a message on the following format

Monitor the status of the node Node. If Flag is true, monitoring is turned on. If Flag is false, monitoring is turned off.

Monitor the status of the node Node. If Flag is true, monitoring is turned on. If Flag is false, monitoring is turned off.

The calling process subscribes or unsubscribes to node status change messages. A nodeup message is delivered to all subscribing processes when a new node is connected, and a nodedown message is delivered when a node is disconnected.

Returns the name of the local node.

Returns the node where Arg originates. Arg can be a process identifier, a reference, a port or a partisan remote reference.

Returns the node specification of the local node. This is the information required when other nodes wish to join this node (See partisan_peer_service:join/1).

Return the partisan node_spec() for node named Node.

Return the tuple {ok, node_spec() for node named Node or the tuple {error, Reason}.

Returns a list of all nodes connected to this node via Partisan. Equivalent to erlang:nodes/1. Sames as calling nodes(visible).

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

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

Returns the partisan encoded pid for the calling process. This is equivalent to calling partisan_remote_ref:from_term(self()).

Returns the partisan encoded pid for the calling process.

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

Equivalent to the native erlang:send_after/4. It calls the native implementation for local destinations. For remote destinations it spawns a process that uses a timer and accepts cancellation ( via cancel_timer/1,2), so this is less efficient than the native implementation.

Start the application.

Stop the application.

Fails with badarg if Arg is a remote reference for another node.

Types

actor/0

-type actor() :: binary().

any_name/0

-type any_name() :: remote_name() | atom().

any_pid/0

-type any_pid() :: remote_pid() | pid().

any_reference/0

-type any_reference() :: remote_reference() | reference().

channel/0

-type channel() :: atom().

channel_opt/0

-type channel_opt() :: net_kernel_opt() | {channel, channel()} | {channel_fallback, boolean()}.

channel_opts/0

-type channel_opts() ::
          #{parallelism := non_neg_integer(), monotonic => boolean(), compression => boolean() | 0..9}.

demonitor_opt/0

-type demonitor_opt() :: flush | info.

forward_opts/0

-type forward_opts() :: partisan_peer_service_manager:forward_opts().

info_opt/0

-type info_opt() ::
          metadata | name | channels | listen_addrs | listen_ip | listen_port | connection_count.

listen_addr/0

-type listen_addr() :: #{ip := inet:ip_address(), port := 1..65535}.

message/0

-type message() :: term().

monitor_nodes_opt/0

-type monitor_nodes_opt() :: net_kernel_opt() | channel_opt().

monitor_opt/0

-type monitor_opt() :: erlang:monitor_option() | {channel, channel()}.

net_kernel_opt/0

-type net_kernel_opt() :: nodedown_reason | connection_id | {node_type, visible | hidden | all}.

node_info/0

-type node_info() :: #{info_opt() => term()}.

node_spec/0

-type node_spec() ::
          #{name := node(), listen_addrs := [listen_addr()], channels := #{channel() => channel_opts()}}.

node_type/0

-type node_type() :: this | known | visible | connected | hidden.

remote_name/0

-type remote_name() :: partisan_remote_ref:n().

remote_pid/0

-type remote_pid() :: partisan_remote_ref:p().

remote_reference/0

-type remote_reference() :: partisan_remote_ref:r().

send_after_dst/0

-type send_after_dst() ::
          pid() | (RegName :: atom()) | (Pid :: remote_pid()) | (RegName :: remote_name()).

send_after_opts/0

-type send_after_opts() :: forward_opts() | [{abs, boolean()}].

send_dst/0

-type send_dst() :: erlang:send_destination() | server_ref().

server_ref/0

-type server_ref() :: partisan_peer_service_manager:server_ref().

time/0

-type time() :: non_neg_integer().

Functions

broadcast(Broadcast, Mod)

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

Broadcasts a message originating from this node.

The message will be delivered to each node at least once. The Mod passed is responsible for handling the message on remote nodes as well as providing some other information both locally and and on other nodes. Mod must be loaded on all members of the clusters and implement the partisan_plumtree_broadcast_handler behaviour.

cancel_timer(Ref)

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

cancel_timer(Ref, Opts)

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

cast_message(ServerRef, Msg)

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

Cast message to a remote ref

cast_message(ServerRef, Msg, Opts)

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

Cast message to registered process on the remote side.

cast_message(Node, ServerRef, Msg, Opts)

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

Cast message to registered process on the remote side.

channel_opts(Channel)

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

Returns a channel with name Name. Fails if a channel named Name doesn't exist.

default_channel()

-spec default_channel() -> channel().

demonitor(MonitorRef)

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

It differs from erlang:demonitor/1 in that it doesn't fail if MonitorRef refers to a monitoring started by another process.

demonitor(MonitorRef, OptionList)

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

disconnect_node(Node)

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

exit(Pid, Reason)

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

forward_message(ServerRef, Msg)

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

Forward message to registered process on the remote side.

forward_message(ServerRef, Msg, Opts)

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

Forward message to registered process on the remote side.

forward_message(Node, ServerRef, Msg, Opts)

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

Forward message to registered process on the remote side.

is_alive()

-spec is_alive() -> boolean().

Returns true if the local node is alive (that is, if the node can be part of a distributed system), otherwise false.

is_connected(NodeOrSpec)

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

Returns the name of the local node.

is_connected(NodeOrSpec, Channel)

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

Returns the name of the local node.

is_fully_connected(NodeOrSpec)

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

Returns the name of the local node.

is_local(Arg)

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

Returns the name of the local node.

is_local_name(Arg)

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

is_local_name(Arg, Name)

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

is_local_pid(Arg)

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

is_local_pid(Arg, Pid)

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

is_local_reference(Arg)

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

is_local_reference(Arg, LocalRef)

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

is_pid(Arg)

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

is_process_alive(Pid)

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

Returns the name of the local node.

is_reference(Arg)

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

Returns the name of the local node.

is_self(Arg)

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

Returns true if Arg is the caller's process identifier.

join(NodeSpec)

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

Shortcut for partisan_peer_service:join/1.

kill_connections(Node)

leave()

-spec leave() -> ok.

Shortcut for partisan_peer_service:leave/0.

make_ref()

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

Returns a new partisan_remote_ref. This is the same as calling partisan_remote_ref:from_term(erlang:make_ref()).

monitor(Term)

This function is deprecated. Use monitor/2 instead..

monitor(Type, Item)

-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 to the entity identified by Item. If the monitored entity does not exist or it changes monitored state, the caller of monitor/2 is notified by a message on the following format: {Tag, MonitorRef, Type, Object, Info}

This is the Partisan's equivalent to erlang:monitor/2.

Failure: notalive if the partisan_monitor server is not alive.

monitor(Type, RegisteredName, Opts)

-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 to the entity identified by Item. If the monitored entity does not exist or it changes monitored state, the caller of monitor/2 is notified by a message on the following format:

{Tag, MonitorRef, Type, Object, Info}

where it differs from the message sent by erlang:monitor/3 only when the item being monitored is a remote process identifier erlang:monitor/3 in which case:

This is the Partisan's equivalent to erlang:monitor/2. It differs from the Erlang implementation only when monitoring a process. For all other cases (monitoring a port or time_offset) this function calls erlang:monitor/2.

As opposed to erlang:monitor/2 this function does not support aliases.

Monitoring a `process`

Creates monitor between the current process and another process identified by Item, which can be a pid() (local or remote), an atom RegisteredName or a tuple {RegisteredName, Node}' for a registered process, located elsewhere.

In the case of a local pid() or a remote pid() A process monitor by name resolves the RegisteredName to pid() or port() only once at the moment of monitor instantiation, later changes to the name registration will not affect the existing monitor.

Failure: if the partisan_monitor server is not alive, a reference will be returned with an immediate 'DOWN' signal with reason notalive.

monitor_node(Node, Flag)

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

Monitor the status of the node Node. If Flag is true, monitoring is turned on. If Flag is false, monitoring is turned off.

Making several calls to monitor_node(Node, true) for the same Node from is not an error; it results in as many independent monitoring instances as the number of different calling processes i.e. If a process has made two calls to monitor_node(Node, true) and Node terminates, only one nodedown message is delivered to the process (this differs from erlang:monitor_node/2).

If Node fails or does not exist, the message {nodedown, Node} is delivered to the calling process. If there is no connection to Node, a nodedown message is delivered. As a result when using a membership strategy that uses a partial view, you can not monitor nodes that are not members of the view.

If Node is the caller's node, the function returns false.

monitor_node(Node, Flag, Options)

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

Monitor the status of the node Node. If Flag is true, monitoring is turned on. If Flag is false, monitoring is turned off.

Making several calls to monitor_node(Node, true) for the same Node from is not an error; it results in as many independent monitoring instances as the number of different calling processes i.e. If a process has made two calls to monitor_node(Node, true) and Node terminates, only one nodedown message is delivered to the process (this differs from erlang:monitor_node/2).

If Node fails or does not exist, the message {nodedown, Node} is delivered to the calling process. If there is no connection to Node, a nodedown message is delivered. As a result when using a membership strategy that uses a partial view, you can not monitor nodes that are not members of the view.

If Node is the caller's node, the function returns false.

monitor_nodes(Flag)

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

monitor_nodes(Flag, Opts)

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

The calling process subscribes or unsubscribes to node status change messages. A nodeup message is delivered to all subscribing processes when a new node is connected, and a nodedown message is delivered when a node is disconnected.

node()

-spec node() -> node().

Returns the name of the local node.

node(Arg)

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

Returns the node where Arg originates. Arg can be a process identifier, a reference, a port or a partisan remote reference.

node_info()

-spec node_info() -> node_info().

node_info(L)

-spec node_info([info_opt()]) -> map().

node_spec()

-spec node_spec() -> node_spec().

Returns the node specification of the local node. This is the information required when other nodes wish to join this node (See partisan_peer_service:join/1).

Notice that the values of the keys must be sorted for the peer service to be able to compare node specifications, and prevent duplicates in the membership view data structure. This is important in case you find yourself building this representation manually in order to implement a particular orchestration strategy. As Erlang maps are naturally sorted, the only property that you need to keep sorted is listen_addrs as it is implemented as a list.

node_spec(Node)

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

Return the partisan node_spec() for node named Node.

This function retrieves the node_spec() from the remote node using RPC and returns {error, Reason} if the RPC fails. Otherwise, assumes the node is running on the same host and returns a node_spec() with with nodename Name and host 'Host' and same metadata as myself/0.

If configuration option connect_disterl is true, the RPC will be implemented using the rpc module. Otherwise it will use partisan_rpc.

You should only use this function when distributed erlang is enabled (configuration option connect_disterl is true) or if the node is running on the same host and you are using this for testing purposes as there is no much sense in running a partisan cluster on a single host.

node_spec(Node, Opts)

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

Return the tuple {ok, node_spec() for node named Node or the tuple {error, Reason}.

This function first checks If there is a partisan connection to Node, if so returns the cached specification that was used for creating the connection. If no connection is present (the case for a p2p topology), then it tries to use @link partisan_rpc} to retrieve the node specification from the remote node. This later alternative requires the partisan configuration forward_opts` to have `broadcast and transitive enabled.

NOTICE: At the moment partisan_rpc might not work correctly w/ a p2p topology.

nodes()

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

Returns a list of all nodes connected to this node via Partisan. Equivalent to erlang:nodes/1. Sames as calling nodes(visible).

Notice that if connect_disterl is true (possibly the case when testing), this function will NOT return the disterl nodes. For that you still need to call erlang:nodes/1.

nodes(Arg)

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

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

Differences with Erlang:

  • hidden - always returns the empty list (there is no concept of hidden nodes in Partisan).
  • this - returns the list containing the result of calling node/0
  • known - will return the nodes known by the partisan_peer_service i.e. partisan_peer_service:members/0 but not the nodes referred to by process identifiers, port identifiers, and references located on this node.
  • visible - equivalent to Erlang.

nodestring()

-spec nodestring() -> binary().

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

process_info(Arg)

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

process_info(Arg, Item)

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

self()

-spec self() -> remote_pid().

Returns the partisan encoded pid for the calling process. This is equivalent to calling partisan_remote_ref:from_term(self()).

Notice that this call is more expensive than It's erlang counterpart. So you might want to cache the result in your process state. See function self/1 which allows you to cache the result in the process dictionary and take notice of the warning related to doing this on an Erlang Shell process.

self(Opts)

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

Returns the partisan encoded pid for the calling process.

If Opts is the empty list, this is equivalent to calling partisan_remote_ref:from_term(self()).

Otherwise, if the option cache is present in Opts the function lazily caches the result of calling partisan_remote_ref:from_term/1 in the process dictionary the first time and retrieves the value in subsequent calls.

NOTICE

You SHOULD avoid using this function in the Erlang Shell. This is because when an Erlang Shell process crashes it will copy the contents of It's dictionary to the new shell process and thus you will end up with the wrong partisan remote reference.

send(Dest, Msg)

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

send(Dest, Msg, Opts)

-spec send(Dest :: send_dst(), Msg :: message(), Opts :: forward_opts()) -> ok | nosuspend | noconnect.

send_after(Time, Destination, Msg)

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

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

send_after(Time, Destination, Message, Opts)

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

Equivalent to the native erlang:send_after/4. It calls the native implementation for local destinations. For remote destinations it spawns a process that uses a timer and accepts cancellation ( via cancel_timer/1,2), so this is less efficient than the native implementation.

spawn(Node, Fun)

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

spawn(Node, Mod, Function, Args)

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

spawn_monitor(Node, Fun)

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

spawn_monitor(Node, Mod, Function, Args)

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

start()

Start the application.

stop()

Stop the application.

whereis(Arg)

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

Fails with badarg if Arg is a remote reference for another node.