partisan (partisan v5.0.2)
View SourceThis 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.
Shortcut for partisan_peer_service:join/1
.
Shortcut for partisan_peer_service:leave/0
.
Returns a new partisan_remote_ref. This is the same as calling partisan_remote_ref:from_term(erlang:make_ref())
.
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
-type actor() :: binary().
-type any_name() :: remote_name() | atom().
-type any_pid() :: remote_pid() | pid().
-type any_reference() :: remote_reference() | reference().
-type channel() :: atom().
-type channel_opt() :: net_kernel_opt() | {channel, channel()} | {channel_fallback, boolean()}.
-type channel_opts() :: #{parallelism := non_neg_integer(), monotonic => boolean(), compression => boolean() | 0..9}.
-type demonitor_opt() :: flush | info.
-type forward_opts() :: partisan_peer_service_manager:forward_opts().
-type info_opt() ::
metadata | name | channels | listen_addrs | listen_ip | listen_port | connection_count.
-type listen_addr() :: #{ip := inet:ip_address(), port := 1..65535}.
-type message() :: term().
-type monitor_nodes_opt() :: net_kernel_opt() | channel_opt().
-type monitor_opt() :: erlang:monitor_option() | {channel, channel()}.
-type net_kernel_opt() :: nodedown_reason | connection_id | {node_type, visible | hidden | all}.
-type node_spec() :: #{name := node(), listen_addrs := [listen_addr()], channels := #{channel() => channel_opts()}}.
-type node_type() :: this | known | visible | connected | hidden.
-type remote_name() :: partisan_remote_ref:n().
-type remote_pid() :: partisan_remote_ref:p().
-type remote_reference() :: partisan_remote_ref:r().
-type send_after_dst() :: pid() | (RegName :: atom()) | (Pid :: remote_pid()) | (RegName :: remote_name()).
-type send_after_opts() :: forward_opts() | [{abs, boolean()}].
-type send_dst() :: erlang:send_destination() | server_ref().
-type server_ref() :: partisan_peer_service_manager:server_ref().
-type time() :: non_neg_integer().
Functions
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.
-spec cast_message(ServerRef :: server_ref(), Msg :: message()) -> ok.
Cast message to a remote ref
-spec cast_message(ServerRef :: server_ref(), Msg :: message(), Opts :: forward_opts()) -> ok.
Cast message to registered process on the remote side.
-spec cast_message(Node :: node(), ServerRef :: server_ref(), Msg :: message(), Opts :: forward_opts()) -> ok.
Cast message to registered process on the remote side.
-spec channel_opts(Channel :: channel()) -> channel_opts() | no_return().
Returns a channel with name Name
. Fails if a channel named Name
doesn't exist.
-spec default_channel() -> channel().
-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.
-spec demonitor(MonitorRef :: reference() | remote_reference(), OptionList :: [demonitor_opt()]) -> boolean().
-spec exit(Pid :: pid() | remote_pid(), Reason :: term()) -> true.
-spec forward_message(ServerRef :: server_ref(), Msg :: message()) -> ok.
Forward message to registered process on the remote side.
-spec forward_message(ServerRef :: server_ref(), Msg :: message(), Opts :: forward_opts()) -> ok.
Forward message to registered process on the remote side.
-spec forward_message(Node :: node(), ServerRef :: server_ref(), Msg :: message(), Opts :: forward_opts()) -> ok.
Forward message to registered process on the remote side.
-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.
Returns the name of the local node.
Returns the name of the local node.
Returns the name of the local node.
-spec is_local(Arg) -> Result when Arg :: pid() | port() | reference() | remote_pid() | remote_reference(), Result :: boolean().
Returns the name of the local node.
-spec is_local_name(Arg :: atom() | remote_name()) -> boolean() | no_return().
-spec is_local_name(Arg :: atom() | remote_name(), Name :: atom()) -> boolean() | no_return().
-spec is_local_pid(Arg :: pid() | remote_pid()) -> boolean() | no_return().
-spec is_local_pid(Arg :: pid() | remote_pid(), Pid :: pid()) -> boolean() | no_return().
-spec is_local_reference(Arg :: reference() | remote_reference()) -> boolean() | no_return().
-spec is_local_reference(Arg :: reference() | remote_reference(), LocalRef :: reference()) -> boolean() | no_return().
-spec is_process_alive(pid() | remote_pid()) -> boolean() | no_return().
Returns the name of the local node.
-spec is_reference(reference() | remote_reference()) -> boolean() | no_return().
Returns the name of the local node.
-spec is_self(Arg) -> Result when Arg :: pid() | remote_pid(), Result :: boolean().
Returns true if Arg
is the caller's process identifier.
-spec join(node_spec()) -> ok.
Shortcut for partisan_peer_service:join/1
.
-spec leave() -> ok.
Shortcut for partisan_peer_service:leave/0
.
-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())
.
-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.
-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:
MonitorRef
is aremote_reference()
Object
is aremote_pid()
orremote_name()
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 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 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
.
-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.
-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 where Arg originates. Arg can be a process identifier, a reference, a port or a partisan remote reference.
-spec node_info() -> node_info().
-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.
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.
-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.
-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
.
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 callingnode/0
known
- will return the nodes known by thepartisan_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.
-spec nodestring() -> binary().
Returns the name of the local node as a binary string.
-spec process_info(Arg :: pid() | remote_pid()) -> [tuple()] | undefined.
-spec process_info(Arg :: pid() | remote_pid(), Item :: atom() | [atom()]) -> [tuple()] | undefined.
-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.
-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.
-spec send(Dest :: send_dst(), Msg :: message(), Opts :: forward_opts()) -> ok | nosuspend | noconnect.
-spec send_after(Time :: time(), Destination :: send_after_dst(), Msg :: message()) -> TRef :: reference().
Equivalent to calling send_after(Time, Dest, Msg, [])
.
-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.
-spec spawn(Node :: node(), Fun :: fun(() -> any())) -> remote_pid().
-spec spawn(Node :: node(), Mod :: module(), Function :: atom(), Args :: [term()]) -> remote_pid().
-spec spawn_monitor(Node :: node(), Fun :: fun(() -> any())) -> {remote_pid(), remote_reference()} | {pid(), reference()}.
-spec spawn_monitor(Node :: node(), Mod :: module(), Function :: atom(), Args :: [term()]) -> {remote_pid(), remote_reference()} | {pid(), reference()}.
Start the application.
Stop the application.
-spec whereis(Arg :: atom() | remote_name()) -> pid() | port() | undefined.
Fails with badarg
if Arg
is a remote reference for another node.