NAME

       pg2 - Distributed named process groups.

DESCRIPTION

       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)