# Module comm

- Description
- Data Types
- Function Index
- Function Details

Message Sending.

Copyright © 2007-2015 Zuse Institute Berlin

Version: $Id$

Authors: Thorsten Schuett (`schuett@zib.de`).

## Description

Message Sending.

Messages consist of a tuple of which the first element is the message's tag, i.e. an atom. Process identifiers depend on local and global target and can also wrap up an reply envelope that can be used to rewrite reply messages.

Sending messages to so-enveloped process identifiers works seamlessly, e.g. a server receiving message {tag, SourcePid} can reply with comm:send(SourcePid, {tag_response}). On the receiving side (a client), the reply message is embedded into the envelope tuple at the specified position. Pids with envelopes can be created using reply_as/3. @end

## Data Types

### channel()

    channel() = main | prio

### envelope()

    envelope() =
        {msg_tag(), any()} |
        {msg_tag(), any(), any()} |
        {msg_tag(), any(), any(), any()} |
        {msg_tag(), any(), any(), any(), any()} |
        {msg_tag(), any(), any(), any(), any(), any()} |
        {msg_tag(), any(), any(), any(), any(), any(), any()} |
        {msg_tag(), any(), any(), any(), any(), any(), any(), any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()} |
        {msg_tag(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any(),
         any()}

### erl_local_pid()

    erl_local_pid() =
        erl_local_pid_plain() | erl_local_pid_with_reply_as()

### erl_local_pid_plain()

    erl_local_pid_plain() = pid() | reg_name()

### erl_local_pid_with_reply_as()

    erl_local_pid_with_reply_as() =
        {erl_local_pid_plain(), e, pos_integer(), envelope()} |
        {erl_local_pid_with_reply_as(), e, pos_integer(), envelope()}

### group_message()

    group_message() =
        {11 | 15, atom(), message() | group_message()}

envelopes:

### message()

    message() = {msg_tag()} | envelope()

### msg_tag()

    msg_tag() = atom() | byte()

byte() in case of compact external atoms. See include/atom_ext.hrl

### mypid()

    mypid() = mypid_plain() | mypid_with_reply_as()

### mypid_plain()

    mypid_plain() =
        {inet:ip_address(),
         comm_server:tcp_port(),
         erl_local_pid_plain()}

### mypid_with_reply_as()

    mypid_with_reply_as() =
        {mypid_plain(), e, pos_integer(), envelope()} |
        {mypid_with_reply_as(), e, pos_integer(), envelope()}

### reg_name()

    reg_name() = atom()

### send_local_options()

    send_local_options() = [{14}]

### send_options()

    send_options() =
        [{shepherd, Pid :: erl_local_pid()} |
         {group_member, Process :: atom()} |
         {channel, channel()} |
         {14} |
         {no_keep_alive}]

## Function Index

forward_to_group_member/2 | Forwards a message to a group member by its process name.
forward_to_registered_proc/2 | Forwards a message to a registered process.
get/2 | Creates the plain PID a process with name Name would have on node Node.
get_ip/1 | Gets the IP address of the given (global) mypid().
get_msg_tag/1 | Gets the tag of a message (the first element of its tuple - should be an atom).
get_plain_pid/1 |
get_port/1 | Gets the port of the given (global) mypid().
init_and_wait_for_valid_IP/0 | Initializes the comm layer by sending a message to known_hosts.
is_local/1 | Check whether a global mypid() can be converted to a local pid of the current node.
is_valid/1 | Check whether the given pid is well formed.
make_global/1 | Convert a local or global erlang pid to a global pid of type mypid() for use in send/2.
make_local/1 | Convert a global mypid() of the current node to a local erlang pid.
reply_as/3 | Encapsulates the given pid (local or global) with the reply_as request, so a send/2 to the generated target will put a reply message at the Nth position of the given envelope.
send/2 | Sends a message to a process given by its pid.
send/3 | Send a message to an arbitrary process with the given options.
send_local/2 | Sends a message to a local process given by its local pid (as returned by self()).
send_local/3 | Sends a message to a local process given by its local pid (as returned by self()).
send_local_after/3 | Sends a message to a local process given by its local pid (as returned by self()) after the given delay in milliseconds.
this/0 | Returns the global pid of the current process.
unpack_cookie/2 |

## Function Details

### send/2

    send(Pid :: mypid(), Msg :: message() | group_message()) -> ok

Sends a message to a process given by its pid.

### send/3

    send(Pid :: mypid(),
         Msg :: message() | group_message(),
         Options :: send_options()) ->
            ok

Send a message to an arbitrary process with the given options. If a shepherd is given, it will be informed when the sending fails; with a message of the form: {send_error, Pid, Msg, Reason}. If a group_member is given, the message is send to an arbitrary process of another node instructing it to forward the message to a process in its group with the given name.

### send_local/2

    send_local(Pid :: erl_local_pid(),
               Msg :: message() | group_message()) ->
                  ok

Sends a message to a local process given by its local pid (as returned by self()).

### send_local/3

    send_local(Pid :: erl_local_pid(),
               Msg :: message() | group_message(),
               Options :: send_local_options()) ->
                  ok

Sends a message to a local process given by its local pid (as returned by self()).

### send_local_after/3

    send_local_after(Delay :: 0..4294967295,
                     Pid :: erl_local_pid(),
                     Msg :: message() | group_message()) ->
                        reference()

Sends a message to a local process given by its local pid (as returned by self()) after the given delay in milliseconds.

### make_global/1

    make_global(Pid :: erl_local_pid() | mypid()) -> mypid()

Convert a local or global erlang pid to a global pid of type mypid() for use in send/2.

### make_local/1

    make_local(Pid :: erl_local_pid() | mypid()) -> erl_local_pid()

Convert a global mypid() of the current node to a local erlang pid.

### this/0

    this() -> mypid_plain()

Returns the global pid of the current process.

### get/2

    get(Name :: erl_local_pid_plain(), Node :: mypid()) ->
           mypid_plain()

Creates the plain PID a process with name Name would have on node Node.

### reply_as/3

    reply_as(Target :: erl_local_pid() | mypid(),
             Nth :: 2..16,
             Envelope :: envelope()) ->
                mypid_with_reply_as() | erl_local_pid_with_reply_as()

Encapsulates the given pid (local or global) with the reply_as request, so a send/2 to the generated target will put a reply message at the Nth position of the given envelope.

### is_valid/1

    is_valid(Pid :: mypid() | any()) -> boolean()

Check whether the given pid is well formed.

### is_local/1

    is_local(Pid :: mypid()) -> boolean()

Check whether a global mypid() can be converted to a local pid of the current node.

### get_ip/1

    get_ip(Pid :: mypid()) -> inet:ip_address()

Gets the IP address of the given (global) mypid().

### get_port/1

    get_port(Pid :: mypid()) -> non_neg_integer()

Gets the port of the given (global) mypid().

### get_msg_tag/1

    get_msg_tag(Msg :: message() | group_message()) -> msg_tag()

Gets the tag of a message (the first element of its tuple - should be an atom).

### unpack_cookie/2

    unpack_cookie(Pid :: mypid(), Msg :: message()) ->
                     {mypid_plain(), message()}

### get_plain_pid/1

    get_plain_pid(Pid :: mypid()) -> mypid_plain()

### forward_to_group_member/2

    forward_to_group_member(Processname :: atom(), Msg :: message()) ->
                               ok

Forwards a message to a group member by its process name. NOTE: Does _not_ warn if the group member does not exist (should only happen during node leave operations).

### forward_to_registered_proc/2

    forward_to_registered_proc(Processname :: atom(),
                               Msg :: message()) ->
                                  ok

Forwards a message to a registered process. NOTE: Does _not_ warn if the process does not exist (should only happen during node leave operations).

### init_and_wait_for_valid_IP/0

    init_and_wait_for_valid_IP() -> ok

Initializes the comm layer by sending a message to known_hosts. A valid IP (and comm:mypid()) for comm:this/0 will be available afterwards. (ugly hack to get a valid ip-address into the comm-layer)

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