erl_connect

C LIBRARY

C LIBRARY SUMMARY

Communicate with Distributed Erlang

DESCRIPTION

This module provides support for communication between distributed
Erlang nodes and C nodes, in a manner that is transparent to Erlang
processes.

A C node appears to Erlang as a
hidden node.
That is, Erlang processes that know the name of the
C node are able to communicate with it in a normal manner, but
the node name will not appear in the listing provided by the
Erlang function nodes/0.

EXPORTS

These functions initialize the erl_connect
module. In particular, they are used to identify the name of the
C-node from which they are called. One of these functions must
be called before any of the other functions in the erl_connect
module are used.

erl_connect_xinit() stores for later use information about
the node's host name host, alive name alive, node
name node, IP address addr, cookie cookie,
and creation number creation. erl_connect_init()
provides an alternative interface which does not require as much
information from the caller. Instead, erl_connect_init()
uses gethostbyname() to obtain default values.

If you use erl_connect_init() your node will have a
short name, i.e., it will not be fully qualified. If you need to
use fully qualified (a.k.a. long) names, use
erl_connect_xinit() instead.

host is the name of the host on which the node is running.

alive is the alivename of the node.

node is the name of the node. The nodename should
be of the form alivename@hostname.

addr is the 32-bit IP address of host.

cookie is the authorization string required for access
to the remote node. If NULL the user HOME directory is
searched for a cookie file .erlang.cookie. The path to
the home directory is retrieved from the environment variable
HOME on Unix and from the HOMEDRIVE and
HOMEPATH variables on Windows. Refer to the auth
module for more details.

creation helps identify a particular instance of a C
node. In particular, it can help prevent us from receiving
messages sent to an earlier process with the same registered
name.

A C node acting as a server will be assigned a creation number
when it calls erl_publish().

number is used by erl_connect_init() to
construct the actual node name. In the second example shown
below, "c17@a.DNS.name" will be the resulting node
name.

erl_xconnect() requires the IP address of the remote
host and the alive name of the remote node
to be specified. erl_connect() provides an alternative
interface, and determines the information from the node name
provided.

addr is the 32-bit IP address of the remote host.

alive is the alivename of the remote node.

node is the name of the remote node.

These functions return an open file descriptor on success, or
a negative value indicating that an error occurred --- in
which case they will set erl_errno to one of:

EHOSTUNREACH

The remote host node is unreachable

ENOMEM

No more memory available.

EIO

I/O error.

Additionally, errno values from
socket(2) and connect(2)
system calls may be propagated into erl_errno.

This function receives a message consisting of a sequence
of bytes in the Erlang external format.

fd is an open descriptor to an Erlang connection.

bufp is a buffer large enough to hold the expected
message.

bufsize indicates the size of bufp.

If a tick occurs, i.e., the Erlang node on the
other end of the connection has polled this node to see if it
is still alive, the function will return ERL_TICK and
no message will be placed in the buffer. Also,
erl_errno will be set to EAGAIN.

On success, the message is placed in the specified buffer
and the function returns the number of bytes actually read. On
failure, the function returns a negative value and will set
erl_errno to one of:

The definition of ErlMessage has changed since
earlier versions of Erl_Interface.

type identifies the type of message, one of
ERL_SEND, ERL_REG_SEND, ERL_LINK,
ERL_UNLINK and ERL_EXIT.

If type contains ERL_SEND
this indicates that an ordinary send operation has taken
place, and emsg->to contains the Pid of the
recipient. If type contains ERL_REG_SEND then a
registered send operation took place, and emsg->from
contains the Pid of the sender. In both cases, the actual
message will be in emsg->msg.

If type contains one of ERL_LINK or
ERL_UNLINK, then emsg->to and emsg->from
contain the pids of the sender and receipient of the link or unlink.
emsg->msg is not used in these cases.

If type contains ERL_EXIT, then this
indicates that a link has been broken. In this case,
emsg->to and emsg->from contain the pids of the
linked processes, and emsg->msg contains the reason for
the exit.

Note

It is the caller's responsibility to release the
memory pointed to by emsg->msg, emsg->to and
emsg->from.

If a tick occurs, i.e., the Erlang node on the
other end of the connection has polled this node to see if it
is still alive, the function will return ERL_TICK
indicating that the tick has been received and responded to,
but no message will be placed in the buffer. In this case you
should call erl_receive_msg() again.

On success, the function returns ERL_MSG and the
Emsg struct will be initialized as described above, or
ERL_TICK, in which case no message is returned. On
failure, the function returns ERL_ERROR and will set
erl_errno to one of:

This function is similar to erl_receive_msg. The
difference is that erl_xreceive_msg expects the buffer to
have been allocated by malloc, and reallocates it if the received
message does not fit into the original buffer. For that reason,
both buffer and buffer length are given as pointers - their values
may change by the call.

On success, the function returns ERL_MSG and the
Emsg struct will be initialized as described above, or
ERL_TICK, in which case no message is returned. On
failure, the function returns ERL_ERROR and will set
erl_errno to one of:

These functions support calling Erlang functions on remote nodes.
erl_rpc_to() sends an rpc request to a remote node and
erl_rpc_from() receives the results of such a call.
erl_rpc() combines the functionality of these two functions
by sending an rpc request and waiting for the results. See also
rpc:call/4.

fd is an open descriptor to an Erlang connection.

timeout is the maximum time (in ms) to wait for
results. Specify ERL_NO_TIMEOUT to wait forever.
When erl_rpc() calls erl_rpc_from(), the call will never
timeout.

mod is the name of the module containing the function
to be run on the remote node.

fun is the name of the function to run.

args is an Erlang list, containing the arguments to be
passed to the function.

emsg is a message containing the result of the
function call.

The actual message returned by the rpc server
is a 2-tuple {rex,Reply}. If you are using
erl_rpc_from() in your code then this is the message you
will need to parse. If you are using erl_rpc() then the
tuple itself is parsed for you, and the message returned to your
program is the erlang term containing Reply only. Replies
to rpc requests are always ERL_SEND messages.

Note

It is the caller's responsibility to free the returned
ETERM structure as well as the memory pointed to by
emsg->msg and emsg->to.

erl_rpc() returns the remote function's return value (or
NULL if it failed). erl_rpc_to() returns 0 on
success, and a negative number on failure. erl_rcp_from()
returns ERL_MSG when successful (with Emsg now
containing the reply tuple), and one of ERL_TICK,
ERL_TIMEOUT and ERL_ERROR otherwise. When failing,
all three functions set erl_errno to one of:

These functions are used by a server process to register
with the local name server epmd, thereby allowing
other processes to send messages by using the registered name.
Before calling either of these functions, the process should
have called bind() and listen() on an open socket.

port is the local name to register, and should be the
same as the port number that was previously bound to the socket.

To unregister with epmd, simply close the returned
descriptor. See also erl_unpublish().

On success, the functions return a descriptor connecting the
calling process to epmd. On failure, they return -1 and set
erl_errno to:

EIO

I/O error

Additionally, errno values from socket(2)
and connect(2) system calls may be propagated
into erl_errno.

This function can be called by a process to unregister a
specified node name from epmd on the localhost. This may be
useful, for example, when epmd has not detected the failure of a
node, and will not allow the name to be reused. If you use this
function to unregister your own process, be sure to also close
the descriptor that was returned by erl_publish().

Note

Careless use of this function may have unpredictable
results, if the registered node is in fact still running.

alive is the name of the node to unregister, i.e., the
first component of the nodename, without the @hostname.

If the node was successfully unregistered from epmd, the
function returns 0. Otherwise, it returns -1 and sets
erl_errno is to EIO.