---
name: "pg2"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:23.2.6+dfsg-1+deb11u1"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/pg2"
---

# pg2(3erl)

Distributed named process groups.

## NAME

pg2 - Distributed named process groups.

## DESCRIPTION

**Warning:**

The *pg2* module is deprecated as of OTP 23 and scheduled for removal in OTP 24. You are advised to replace the usage of *pg2* with pg. *pg* has a similar API, but with an implementation that is more scalable. See the documentation of *pg* for more information about differences.

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.

## 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}\

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}}
```

Types:

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}}
```

Types:

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}}
```

Types:

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}}
```

Types:

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(7)](/kernel/7.md)* for this.

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

Returns a list of all known groups.

## SEE ALSO

*[kernel(7)](/kernel/7.md)*