Distributed named process groups.
This module implements process groups. Each message can be sent to one, some, or all group members.
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.
Warning!
This module is used by module
disk_log
for
managing distributed disk logs. The disk log names are used as
group names, which means that some action can be needed
to avoid name clashes.
Functions
create(Name :: name()) -> ok
Creates a new, empty process group. The group is globally visible on all nodes. If the group exists, nothing happens.
delete(Name :: name()) -> ok
Deletes a process group.
get_closest_pid(Name) -> pid() | {error, Reason}
Name = name()
Reason = {no_process, Name} | {no_such_group, Name}
A useful dispatch function that can be used from client functions. It returns a process on the local node, if such a process exists. Otherwise, it selects one randomly.
get_local_members(Name) ->
[pid()] | {error, {no_such_group, Name}}
Name = name()
Returns all processes running on the local node in the
group Name
. This function is to be used from
within a client function that accesses the group. It is therefore
optimized for speed.
get_members(Name) -> [pid()] | {error, {no_such_group, Name}}
Name = name()
Returns all processes in the group Name
. This
function is to be used from within a client function that
accesses the group. It is therefore optimized for speed.
join(Name, Pid :: pid()) -> ok | {error, {no_such_group, Name}}
Name = name()
Joins the process Pid
to the group Name
.
A process can join a group many times and must then
leave the group the same number of times.
leave(Name, Pid :: pid()) -> ok | {error, {no_such_group, Name}}
Name = name()
Makes the process Pid
leave the group Name
.
If the process is not a member of the group, ok
is
returned.
start() -> {ok, pid()} | {error, any()}
start_link() -> {ok, pid()} | {error, any()}
Starts the pg2
server. Normally, the server does not need
to be started explicitly, as it is started dynamically if it
is needed. This is useful during development, but in a
target system the server is to be started explicitly. Use the
configuration parameters for
kernel(6)
for this.
which_groups() -> [Name :: name()]
Returns a list of all known groups.