Pg2

v1.0.0

Pg2 v1.0.0 Pg2

A slightly opinionated wrapper around :pg2. Pg2 adds conveniences like automatic group creation in join, and returns empty lists when querying membership of non-existant groups. See the documenation for each method for specific differences from :pg2

Link to this section Summary

Types

group_name()

Functions

create(group_name)

Creates a new, empty process group. The group is globally visible on all nodes. If the group exists, nothing happens

delete(group_name)

Deletes a process group

get_closest_pid(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(group_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(group_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(group_name, pid \\ :self)

Joins the process pid to the group group_name. A process can join a group many times and must then leave the group the same number of times

leave(group_name, pid \\ :self)

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

start()

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

start_link()

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()

Returns a list of all known groups

Link to this section Types

Link to this type group_name() 
group_name() :: any

Link to this section Functions

Link to this function create(group_name) 
create(group_name) :: :ok

Creates a new, empty process group. The group is globally visible on all nodes. If the group exists, nothing happens.

Link to this function delete(group_name) 
delete(group_name) :: :ok

Deletes a process group.

Link to this function get_closest_pid(group_name) 
get_closest_pid(group_name) :: :ok | {:no_process, 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.

Differences from :pg2

  • this function returns {:no_process, group_name} if the group does not exist, rather than {:no_such_group, group_name}
Link to this function get_local_members(group_name) 
get_local_members(group_name) :: [pid]

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.

Differences from :pg2

  • this function returns an empty list if the group does not exist.
Link to this function get_members(group_name) 
get_members(group_name) :: [pid]

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.

Differences from :pg2

  • this function returns an empty list if the group does not exist.
Link to this function join(group_name, pid \\ :self) 
join(group_name, pid | :self) :: :ok

Joins the process pid to the group group_name. A process can join a group many times and must then leave the group the same number of times.

Differences from :pg2

  • this function defaults the pid to self()
  • this function creates the group if it does not exist
Link to this function leave(group_name, pid \\ :self) 
leave(group_name, pid | :self) :: :ok

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

Differences from :pg2

  • defaults the pid to self()
  • returns :ok if the group does not exist
  • deletes the group if it is empty
Link to this function start() 
start() :: {: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.

Link to this function start_link() 
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.

Link to this function which_groups() 
which_groups() :: [group_name]

Returns a list of all known groups.