# Module pid_groups

- Description
- Data Types
- Function Index
- Function Details

Process groups.

Copyright © 2007-2016 Zuse Institute Berlin

Version: $Id$

Behaviours: `gen_component`.

Authors: Thorsten Schuett (`schuett@zib.de`), Florian Schintke (`schintke@zib.de`).

## Description

Process groups.

This module provides a mechanism to implement process groups. Within a process group, the names of processes have to be unique, but the same name can be used in different groups. The motivation for this module was to run several scalaris nodes in one erlang vm for debugging. But for the processes forming a scalaris node being able to talk to each other, they have to know their names (dht_node, config, etc.). This module allows the processes to keep their names.

When a new process group is created, a unique "groupname" is created, which has to be shared by all nodes in this group.

## Data Types

### groupname()

    groupname() =
        atom() | pos_integer() | {atom(), pos_integer() | atom()}

### pidname()

    pidname() =
        nonempty_string() |
        atom() |
        {atom(), atom()} |
        {atom(), pos_integer()} |
        {{atom(), pos_integer()}, atom()}

## Function Index

add/3 | Third party register: add a pid with a given pidname (role) to a group.
filename_to_group/1 | only supports the form {atom(), pos_integer()} | atom().
find_a/1 | find a pid with the given name (search in own group first), otherwise allow round-robin returns of all the pids with this name in any group.
find_all/1 |
get_my/1 | Gets the Pid of the current process' group member with the given name.
get_web_debug_info/2 | get info about a process.
group_and_name_of/1 | lookup group and pid name of a process via its pid.
group_of/1 |
group_to_filename/1 | only supports the form {atom(), pos_integer()} | atom().
group_to_string/1 |
group_with/1 | find a process group with a given process name inside.
groups/0 |
groups_as_json/0 |
groups_with/1 | find all process groups with a given process name inside.
hide/1 | hide a group of processes temporarily (for paused groups in unit tests).
join/1 | Current process joins the group GrpName, but has no process name.
join_as/2 | Current process joins the group GrpName with process name Pidname.
members/1 |
members_by_name/1 |
members_by_name_as_json/1 | find processes in a group (for web interface).
my_groupname/0 |
my_members/0 |
my_pidname/0 |
my_tab2list/0 |
new/0 | create a new group with a random name.
new/1 | create a new group with a given prefix.
pid_of/2 | lookup a pid via its group name and pid name.
pid_to_name/1 | Resolve a local pid to its name.
pids_to_names/2 | Resolve (local and remote) pids to names.
processes/0 |
start_gen_component/5 |
start_link/0 | Starts the server.
string_to_group/1 |
tab2list/0 |
unhide/1 |

## Function Details

### start_gen_component/5

    start_gen_component(Module :: module(),
                        Handler :: gen_component:handler(),
                        Args :: term(),
                        Options :: [gen_component:option()],
                        Self :: pid()) ->
                           no_return() | ok

### new/0

    new() -> groupname()

create a new group with a random name.

### new/1

    new(Prefix :: atom()) -> groupname()

create a new group with a given prefix.

### join/1

    join(GrpName :: groupname()) -> ok

Current process joins the group GrpName, but has no process name.

DEPRECATED! client processes should not join groups. Other processes should have a unique role name and join via join_as or add.

### join_as/2

    join_as(GrpName :: groupname(), PidName :: pidname()) -> ok

Current process joins the group GrpName with process name Pidname.

### add/3

    add(GrpName :: groupname(), PidName :: pidname(), Pid :: pid()) ->
           ok

Third party register: add a pid with a given pidname (role) to a group.

### my_groupname/0

    my_groupname() -> groupname() | undefined

### my_pidname/0

    my_pidname() -> pidname() | undefined

### get_my/1

    get_my(PidName :: pidname()) -> pid() | failed

Gets the Pid of the current process' group member with the given name.

### my_members/0

    my_members() -> [pid()]

### my_tab2list/0

    my_tab2list() -> [{{groupname(), pidname()}, pid()}]

### pid_of/2

    pid_of(GrpName :: groupname(), PidName :: pidname()) ->
              pid() | failed

lookup a pid via its group name and pid name.

### group_and_name_of/1

    group_and_name_of(Pid :: pid()) ->
                         {groupname(), pidname()} | failed

lookup group and pid name of a process via its pid.

### group_of/1

    group_of(Pid :: pid()) -> groupname() | failed

### group_with/1

    group_with(PidName :: pidname()) -> groupname() | failed

find a process group with a given process name inside

### groups_with/1

    groups_with(PidName :: pidname()) -> [groupname()] | failed

find all process groups with a given process name inside

### find_a/1

    find_a(PidName :: pidname()) -> pid() | failed

find a pid with the given name (search in own group first), otherwise allow round-robin returns of all the pids with this name in any group

### find_all/1

    find_all(PidName :: pidname()) -> [pid()]

### members/1

    members(GrpName :: groupname()) -> [pid()]

### members_by_name/1

    members_by_name(GrpName :: groupname()) -> [pidname()]

### processes/0

    processes() -> [pid()]

### groups/0

    groups() -> [groupname()]

### tab2list/0

    tab2list() -> [{{groupname(), pidname()}, pid()}]

### group_to_filename/1

    group_to_filename(GrpName :: groupname()) -> nonempty_string()

only supports the form {atom(), pos_integer()} | atom(). Not deeper nested structures.

### filename_to_group/1

    filename_to_group(GrpName :: nonempty_string()) -> groupname()

only supports the form {atom(), pos_integer()} | atom(). Not deeper nested structures.

### pid_to_name/1

    pid_to_name(Pid :: pid() | {groupname(), pidname()}) -> string()

Resolve a local pid to its name.

### pids_to_names/2

    pids_to_names(Pids :: [comm:mypid()], Timeout :: pos_integer()) ->
                     [string()]

Resolve (local and remote) pids to names.

### get_web_debug_info/2

    get_web_debug_info(GrpStr :: string(), PidNameString :: string()) ->
                          {struct,
                           [{pairs,
                             {array,
                              [{struct,
                                [{key | value, nonempty_string()}]}]}}]}

get info about a process

### groups_as_json/0

    groups_as_json() ->
                      {array,
                       [{struct,
                         [{id | text, nonempty_string()} |
                          {leaf, false}]}]}

### members_by_name_as_json/1

    members_by_name_as_json(GrpString :: nonempty_string()) ->
                               {array,
                                [{struct,
                                  [{id | text, nonempty_string()} |
                                   {leaf, true}]}]}

find processes in a group (for web interface)

### group_to_string/1

    group_to_string(Group :: groupname()) -> string()

### string_to_group/1

    string_to_group(GrpStr :: nonempty_string()) ->
                       groupname() | failed

### hide/1

    hide(GrpName :: groupname()) -> ok

hide a group of processes temporarily (for paused groups in unit tests)

### unhide/1

    unhide(GrpName :: groupname()) -> ok

### start_link/0

    start_link() -> {ok, pid()}

Starts the server

Generated by EDoc, Feb 29 2016, 16:12:16.