The identifier of the scope gen_server and ETS table.
pg
Description
This module implements a distributed eventual consistent process group registry.
Up until OTP 17 there used to exist an experimental pg module in stdlib. This pg module is not the same module as that experimental pg module, and only share the same module name.
A group of processes can be accessed by a common name. For example, if there is a group named foobar, there can be a set of processes (which can be located on different nodes) that are all members of the group foobar. There are no special functions for sending a message to the group. Instead, client functions are to be written with the functions get_members/1 and get_local_members/1 to determine which processes are members of the group. Then the message can be sent to one or more group members.
If a member terminates, it is automatically removed from the group.
A process may join multiple groups. It may join the same group multiple times. It is only allowed to join processes running on local node.
Process Groups implement strong eventual consistency. Process Groups membership view may temporarily diverge. For example, when processes on node1 and node2 join concurrently, node3 and node4 may receive updates in a different order.
Membership view is not transitive. If node1 is not directly connected to node2, they will not see each other groups. But if both are connected to node3, node3 will have the full view.
Groups are automatically created when any process joins, and are removed when all processes leave the group. Non-existing group is considered empty (containing no processes).
Process groups can be organised into multiple scopes. Scopes are completely independent of each other. A process may join any number of groups in any number of scopes. Scopes are designed to decouple single mesh into a set of overlay networks, reducing amount of traffic required to propagate group membership information. Default scope pg is started automatically when kernel(6) is configured to do so.
If the shards_and_metadata kernel application parameter is enabled when starting the scope, the server will start with the shards_and_metadata feature enabled. When enabled a member on the form {pid(), Metadata :: any()} can also join or leave the groups.
In addition, when the feature is enabled, besides the singleton group defined above, `pg` can also join or leave to a range of shards for a sharded group. For example, assume we did join([{1, 5}], group, [Pid1]) and then join([{4, 8}], group, [{Pid2, Metadata2}]). If we do get_all_members(4, group) it will return [Pid1, {Pid2, Metadata2}], and if we do get_all_members(2, group) it will return [Pid1]. This is especially useful for service discovery on sharded services. Servers can publish the shard ranges that it serves, and client can get the server pid without explicitly knowing the shard map.
`pg` server prior to OTP 26 will crash if any other node has enabled shards_and_metadata feature in the cluster. `pg` server at OTP 26 will only send or receive singleton group updates with only pid type members. `pg` server at OTP 27 or above without shards_and_metadata enabled will only receive singleton group updates with only pid from other nodes, but it can join/leave sharded group with metadata in members locally, and only servers with shards_and_metadata enabled can receive these updates. `pg` server with shards_and_metadata enabled will have the full functionalities.
Note
Scope name is used to register process locally, and to name an ETS table. If there is another process registered under this name, or another ETS table exists, scope fails to start.
Local membership is not preserved if scope process exits and restarts.
A scope can be kept local-only by using a scope name that is unique cluster-wide, e.g. the node name:
- pg:start_link(node()).
Data Types
The identifier of a process group.
The metadata of a process.
The tuple of a process identifier and its metadata.
A member that can join or leave the groups.
A list of members that can join or leave the groups.
A non-negative integer shard id.
shard_range() = {shard(), shard()}
A shard range (both sides inclusive).
A list of shard ranges.
update() =
{group(), singleton | shard_ranges(), members(), members()}
{group(), singleton | shard_ranges(), members(), members()}
An update request.
A list of update requests.
leave_error_singleton() = not_joined
Error when doing a single leave request for a singleton group
features() = #{shards_and_metadata => boolean()}
A map of enabled features.
monitor_scope_return_singleton() =
{reference(), #{group() => [pid()]}}
{reference(), #{group() => [pid()]}}
A monitor scope reply for singleton group.
A monitor group reply for singleton group.
monitor_message_singleton() =
{reference(), join | leave, group(), [pid()]}
{reference(), join | leave, group(), [pid()]}
Group membership update message without shards and metadata.
Group membership update message.
start_link() -> gen_server:start_ret()OTP 23.0
Starts the default pg scope within supervision tree. Kernel may be configured to do it automatically, see kernel(6) configuration manual.
start(Scope :: atom()) -> gen_server:start_ret()OTP 23.0
start_link(Scope :: atom()) -> gen_server:start_ret()OTP 23.0
Starts additional scope.
join(Group :: group(), MemberOrMembers :: member() | members()) ->
okOTP 23.0
join(Scope :: atom() | (ShardRanges :: shard_ranges()),
Group :: group(),
MemberOrMembers :: member() | members()) ->
okOTP 23.0
join(Scope :: atom(),
ShardRanges :: shard_ranges(),
Group :: group(),
MemberOrMembers :: member() | members()) ->
okOTP 27.0
If ShardRanges is not specified, joins single member or multiple members MemberOrMembers to the singleton group Group. If ShardRanges is specified, joins MemberOrMembers to the ShardRanges of the sharded group Group. A member can join a group many times and must then leave the group the same number of times.
MemberOrMembers may contain the same member multiple times.
leave(Group :: group(), MemberOrMembers :: member() | members()) ->
ok | leave_error_singleton()OTP 23.0
leave(Scope :: atom() | (ShardRanges :: shard_ranges()),
Group :: group(),
MemberOrMembers :: member() | members()) ->
ok | leave_error_singleton() | updates()OTP 23.0
leave(Scope :: atom(),
ShardRanges :: shard_ranges(),
Group :: group(),
MemberOrMembers :: member() | members()) ->
updates()OTP 27.0
If ShardRanges is not specified, makes the member or multiple members MemberOrMembers leave the singleton group Group. If ShardRanges is specified, makes MemberOrMembers leave the ShardRanges of the sharded group Group.
Leaving one or more members of a singleton group will success and return atom ok even if some members are not joined, but if the entire leave result in a non-op, an atom not_joined will be returned. This is specially for backward compatibility
For sharded groups, leaving a member that has not joined the entire requested shard ranges will silently work as a non-op for not joined portion. The function will return the actual acted updates.
update(Updates :: updates()) -> updates()OTP 27.0
update(Scope :: atom(), Updates :: updates()) -> updates()OTP 27.0
Makes group membership updates, each update is a tuple update() :: {Group, Position, RemovedMembers, AddedMembers} where Position is either an atom singleton or a list of shard ranges, indicating whether this operation is on a singleton group or specified ranges of a sharded group. AddedMembers is the list of members to be added, and RemovedMembers is the list of members to be removed.
The algorithm promises that an update() looks like an 'atomic' operation by a single shard's view if the input shard ranges are disjoint. It means that a get_members query will either return the expected member list before an update, or after an update. It won't return with anything else like an intermediate step.
Removing a member that has not joined will silently work as a non-op for not joined portion. The function will return the actual acted updates.
monitor_scope() -> monitor_scope_return_singleton()OTP 25.1
monitor_scope(Scope :: atom()) -> monitor_scope_return_singleton()OTP 25.1
monitor_scope(Scope :: atom(), Features :: features()) ->
monitor_scope_return_singleton() |
monitor_message()OTP 27.0
Subscribes the caller to updates from the specified scope. Returns content of the entire scope and a reference to match the upcoming notifications. The content is a map by default; or updates() if shards_and_metadata is true in Features, the same as the input in update/2.
Whenever any group membership changes, an update message is sent to the subscriber. If feature shards_and_metadata is not enabled, the messages will be:
{Ref, join, Group, [JoinPid1, JoinPid2]}{Ref, leave, Group, [LeavePid1]}If feature shards_and_metadata is enabled, the messages will be:
{Ref, [{Group, Position, RemovedMembers,
AddedMembers}]}See update/2.
monitor(Group :: group()) -> monitor_group_return_singleton()OTP 25.1
monitor(Scope :: atom(), Group :: group()) ->
monitor_group_return_singleton()OTP 25.1
monitor(Scope :: atom(), Group :: group(), Features :: features()) ->
monitor_group_return_singleton() | monitor_message()OTP 27.0
Subscribes the caller to updates for the specified group. Returns content currently in the group, and a reference to match the upcoming notifications. The content is a list of processes by default; or updates() if shards_and_metadata is true in Features, the same as the input in update/2.
Seemonitor_scope/0 for the update message structure.
demonitor(Ref :: reference()) -> ok | falseOTP 25.1
demonitor(Scope :: atom(), Ref :: reference()) -> ok | falseOTP 25.1
Unsubscribes the caller from updates (scope or group). Flushes all outstanding updates that were already in the message queue of the calling process.
get_all_members(Group :: group()) -> members()OTP 23.0
get_all_members(Scope :: atom() | (Shard :: shard()),
Group :: group()) ->
members()OTP 23.0
get_all_members(Scope :: atom(),
Shard :: shard(),
Group :: group()) ->
members()OTP 27.0
Read members in singleton group Group, or Shard of sharded group Group, depending on if Shard is specified in the input. Members are returned in no specific order. This function is optimised for speed.
get_all_local_members(Group :: group()) -> members()OTP 23.0
get_all_local_members(Scope :: atom() | (Shard :: shard()),
Group :: group()) ->
members()OTP 23.0
get_all_local_members(Scope :: atom(),
Shard :: shard(),
Group :: group()) ->
members()OTP 27.0
Read members in singleton group Group, or Shard of sharded group Group, depending on if Shard is specified in the input. Only members running on the local node are returned, and members are returned in no specific order. This function is optimised for speed.
get_members(Group :: group()) -> [pid()]OTP 23.0
get_members(Scope :: atom() | (Shard :: shard()),
Group :: group()) ->
[pid()]OTP 23.0
get_members(Scope :: atom(), Shard :: shard(), Group :: group()) ->
[pid()]OTP 27.0
Read members in singleton group Group, or Shard of sharded group Group, depending on if Shard is specified in the input. Only pid() type members are returned, and members are returned in no specific order. This function is for backward compatibility.
get_local_members(Group :: group()) -> [pid()]OTP 23.0
get_local_members(Scope :: atom() | (Shard :: shard()),
Group :: group()) ->
[pid()]OTP 23.0
get_local_members(Scope :: atom(),
Shard :: shard(),
Group :: group()) ->
[pid()]OTP 27.0
Read members in singleton group Group, or Shard of sharded group Group, depending on if Shard is specified in the input. Only pid() type members which are also running on the local node are returned, and members are returned in no specific order. This function is for backward compatibility.
which_groups() -> [Group :: group()]OTP 23.0
which_groups(Scope :: atom()) -> [Group :: group()]OTP 23.0
Returns a list of all known singleton groups.
which_local_groups() -> [Group :: group()]OTP 23.0
which_local_groups(Scope :: atom()) -> [Group :: group()]OTP 23.0
Returns a list of singleton groups that have any local member joined.
which_sharded_groups() -> [Group :: group()]OTP 27.0
which_sharded_groups(Scope :: atom()) -> [Group :: group()]OTP 27.0
Returns a list of all known sharded groups.
which_sharded_local_groups() -> [Group :: group()]OTP 27.0
which_sharded_local_groups(Scope :: atom()) -> [Group :: group()]OTP 27.0
Returns a list of all known sharded groups that have any local member joined.
which_shard_ranges(Group :: group()) ->
ShardRanges :: shard_ranges()OTP 27.0
which_shard_ranges(Scope :: atom(), Group :: group()) ->
ShardRanges :: shard_ranges()OTP 27.0
Returns a list of all known shard ranges of a sharded group.
which_local_shard_ranges(Group :: group) ->
ShardRanges :: shard_ranges()OTP 27.0
which_local_shard_ranges(Scope :: atom(), Group :: group()) ->
ShardRanges :: shard_ranges()OTP 27.0
Returns a list of shard ranges of a sharded group that have any local member joined.