View Source partisan_remote_ref (partisan v5.0.0-beta.14)
Remote references are Partisan's representation for remote process identifiers (pid()
), registered names and references (reference()
).
Distributed Erlang (disterl) will transform the representation of process identifiers, registered names and references when they are sent to a remote node. This is done to disambiguate between remote and local instances. Because Partisan doesn't use disterl it needs to implement this same disambiguation mechanism somehow. As disterl's implementation is done by the BEAM internally and not API is exposed, this module is required to achieve a similar result.
representation
Representation
In cases where lots of references are stored in process state, ets
and specially where those are uses as keys, a binary format is preferable to the tuple format in order to save memory and avoid copying the term every time a message is send between processes (by leveraging off-heap binary storage).
- references as binary URIs
- references as tuples
The representation to use is controlled by the configuration option remote_ref_as_uri`. If `true
this module will generate references as binary URIs. Otherwise it will generate them as tuples.r
URI Representation
1> partisan_remote_ref:from_term(self()).
<<"partisan:pid:nonode@nohost:0.1062.0">>
URI Padding
For those cases where the resulting references are smaller than 64 bytes ( and thus will be stored on the process heap) this module can pad the generated bianry URIs to 65 bytes, thus forcing them to be stored off-heap. This is controlled with the configuration option remote_ref_binary_padding
.
1> partisan_config:set(remote_ref_binary_padding, false).
2> partisan_remote_ref:from_term(self()).
<<"partisan:pid:nonode@nohost:0.1062.0">>
3> partisan_config:set(remote_ref_binary_padding, true).
ok
4> partisan_remote_ref:from_term(self()).
<<"partisan:pid:nonode@nohost:0.1062.0:"...>>
Tuple Representation
1> partisan_remote_ref:from_term(self()).
{partisan_remote_reference,
nonode@nohost,
{partisan_process_reference,"<0.1062.0>"}}
Link to this section Summary
Functions
Name
and a node Node
and returns a partisan remote reference.erlang:whereis/1
which means the check can fail if the process has died (and thus is no longer registered).Ref
is located in node Node
.Link to this section Types
-type encoded_name() :: {encoded_name, list()}.
-type encoded_pid() :: {encoded_pid, list()}.
-type encoded_ref() :: {encoded_ref, list()}.
-type n() :: tuple_ref(encoded_name()) | uri().
-type p() :: tuple_ref(encoded_pid()) | uri().
-type r() :: tuple_ref(encoded_ref()) | uri().
-type target() :: encoded_pid() | encoded_ref() | encoded_name().
-type tuple_ref(T) :: {partisan_remote_ref, node(), T}.
-type uri() :: <<_:64, _:_*8>>.
Link to this section Functions
-spec from_term(pid() | reference() | atom() | {atom(), node()}) -> t() | no_return().
-spec from_term(Name :: atom(), Node :: node()) -> n() | no_return().
Name
and a node Node
and returns a partisan remote reference.
erlang:whereis/1
which means the check can fail if the process has died (and thus is no longer registered).
-spec is_local(Ref :: t()) -> boolean() | no_return().
-spec is_local(Ref :: t(), Node :: node()) -> boolean() | no_return().
Ref
is located in node Node
.
-spec is_name(any()) -> boolean().
-spec is_name(Ref :: any(), Name :: atom()) -> boolean().
-spec is_pid(any()) -> boolean().
-spec is_reference(any()) -> boolean().
-spec is_type(any()) -> boolean().
-spec node(Ref :: t()) -> node() | no_return().
-spec nodestring(Ref :: t()) -> binary() | no_return().
-spec to_term(t()) -> pid() | reference() | atom() | no_return().