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) for this.

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

              Returns a list of all known groups.

SEE ALSO

       kernel(7)