pg2

Module

pg2

Module summary

Distributed Named Process Groups

Description

This module implements process groups. Each message may be sent to one, some, or all members of the group.

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) which are all members of the group foobar. There are no special functions for sending a message to the group. Instead, client functions should be written with the functions get_members/1 and get_local_members/1 to find out which processes are members of the group. Then the message can be sent to one or more members of the group.

If a member terminates, it is automatically removed from the group.

Data types

name() = any()

The name of a process group.

Exports

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}

Types:

Name = name()
Reason = {no_process, Name} | {no_such_group, Name}

This is a useful dispatch function which can be used from client functions. It returns a process on the local node, if such a process exist. Otherwise, it chooses one randomly.

get_members(Name) -> [pid()] | {error, {no_such_group, Name}}

Types:

Name = name()

Returns all processes in the group Name. This function should be used from within a client function that accesses the group. It is therefore optimized for speed.

get_local_members(Name) ->                      [pid()] | {error, {no_such_group, Name}}

Types:

Name = name()

Returns all processes running on the local node in the group Name. This function should 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}}

Types:

Name = name()

Joins the process Pid to the group Name. A process can join a group several times; it must then leave the group the same number of times.

leave(Name, Pid :: pid()) -> ok | {error, {no_such_group, Name}}

Types:

Name = name()

Makes the process Pid leave the group Name. If the process is not a member of the group, ok is returned.

which_groups() -> [Name :: name()]

Returns a list of all known groups.

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 should be started explicitly. Use configuration parameters for kernel for this.

See Also

kernel(6)