From 5f5fb466630db9dc8e17895c90ed74105852e827 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Fri, 21 Oct 2016 15:44:49 +0200 Subject: erl_interface: Remove CDATA tag except for example code --- lib/erl_interface/doc/src/ei_connect.xml | 334 +++++++++++++++---------------- 1 file changed, 167 insertions(+), 167 deletions(-) (limited to 'lib/erl_interface/doc/src/ei_connect.xml') diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index be34fb7c53..607a7cbff4 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -44,32 +44,32 @@ erlang:nodes/0 in ERTS.

-

The environment variable can be used +

The environment variable ERL_EPMD_PORT can be used to indicate which logical cluster a C-node belongs to.

Time-Out Functions

Most functions appear in a version with the suffix - appended to the function name. Those functions + _tmo appended to the function name. Those functions take an extra argument, a time-out in milliseconds. The semantics is this: for each communication primitive involved in the operation, if the primitive does not complete within the time specified, the function returns an error and - is set to . + erl_errno is set to ETIMEDOUT. With communication primitive is meant an operation on the socket, like - , , - , or .

+ connect, accept, + recv, or send.

Clearly the time-outs are for implementing fault tolerance, - not to keep hard real-time promises. The functions + not to keep hard real-time promises. The _tmo functions are for detecting non-responsive peers and to avoid blocking on socket operations.

-

A time-out value of (zero) means that time-outs are - disabled. Calling a function with the last - argument as is therefore the same thing as calling - the function without the suffix.

+

A time-out value of 0 (zero) means that time-outs are + disabled. Calling a _tmo function with the last + argument as 0 is therefore the same thing as calling + the function without the _tmo suffix.

As with all other functions starting with ei_, you are not expected @@ -80,9 +80,9 @@ avoid problems, leave the socket options alone. ei handles any socket options that need modification.

-

In all other senses, the functions inherit all +

In all other senses, the _tmo functions inherit all the return values and the semantics from the functions without - the suffix.

+ the _tmo suffix.

@@ -105,15 +105,15 @@ connection from a client process.

-

is the C-node structure.

+

ec is the C-node structure.

 -

is an open socket descriptor on - which has previously been called.

+

listensock is an open socket descriptor on + which listen() has previously been called.

 -

is a pointer to an - struct, described as follows:

+

conp is a pointer to an + ErlConnect struct, described as follows:

 -

On success, is filled in with the address and +

On success, conp is filled in with the address and node name of the connecting client and a file descriptor is - returned. On failure, is returned and - is set to .

+ returned. On failure, ERL_ERROR is returned and + erl_errno is set to EIO.

@@ -146,34 +146,34 @@ typedef struct { Establish a connection to an Erlang node.

Sets up a connection to an Erlang node.

-

requires the IP address of the +

ei_xconnect() requires the IP address of the remote host and the alive name of the remote node to be - specified. provides an alternative + specified. ei_connect() provides an alternative interface and determines the information from the node name provided.

- is the 32-bit IP address of the remote + addr is the 32-bit IP address of the remote host. - is the alivename of the remote node. + alive is the alivename of the remote node. - is the name 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 the latter - case they set to one of the + case they set erl_errno to one of the following:

- - The remote host is unreachable. - + EHOSTUNREACH + The remote host node is unreachable. + ENOMEM No more memory is available. - + EIO I/O error. -

Also, values from - (2) and - (2) - system calls may be propagated into .

+

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

Example:

intei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation) Initialize for a connection. -

Initializes the structure, to +

Initializes the ec structure, to identify the node name and cookie of the server. One of them must be called before other functions that works on the - type or a file descriptor associated with + ei_cnode type or a file descriptor associated with a connection to another node is used.

-

is a structure containing information about - the C-node. It is used in other functions +

ec is a structure containing information about + the C-node. It is used in other ei functions for connecting and receiving data.

 -

is the registered name of the +

this_node_name is the registered name of the process (the name before '@').

 -

is the cookie for the node.

+

cookie is the cookie for the node.

 -

identifies a specific instance of a +

creation identifies a specific instance of a C-node. It can help prevent the node from receiving messages sent to an earlier process with the same registered name.

 -

is the name of the machine we are +

thishostname is the name of the machine we are running on. If long names are to be used, they are to be fully - qualified (that is, - instead of ).

+ qualified (that is, durin.erix.ericsson.se + instead of durin).

 -

is the registered name of the +

thisalivename is the registered name of the process.

 -

is the full name of the node, - that is, .

+

thisnodename is the full name of the node, + that is, einode@durin.

 -

if the IP address of the host.

+

thispaddr if the IP address of the host.

A C-node acting as a server is assigned a creation - number when it calls .

+ number when it calls ei_publish().

A connection is closed by simply closing the socket. For information about how to close the socket gracefully (when there are outgoing packets before close), see the relevant system @@ -306,32 +306,32 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { 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 and + have called bind() and listen() on an open socket.

-

is the C-node structure.

+

ec is the C-node structure.

 -

is the local name to register, and is to +

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

 -

is the 32-bit IP address of the local +

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

To unregister with EPMD, simply close the returned descriptor. Do - not use , which is deprecated + not use ei_unpublish(), which is deprecated anyway.

On success, the function returns a descriptor connecting the calling process to EPMD. On failure, -1 is returned and - is set to .

-

Also, values from - (2) and - (2) system calls may be propagated - into .

+ erl_errno is set to EIO.

+

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

 @@ -353,34 +353,34 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { of bytes in the Erlang external format.

-

is an open descriptor to an Erlang +

fd is an open descriptor to an Erlang connection. It is obtained from a previous - or .

+ ei_connect or ei_accept.

 -

is a buffer large enough to hold the +

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

 -

indicates the size of - .

+

bufsize indicates the size of + bufp.

If a tick occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function returns and + is still alive, the function returns ERL_TICK and no message is placed in the buffer. Also, - is set to .

+ erl_errno is 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 and sets - to one of the following:

+ failure, the function returns ERL_ERROR and sets + erl_errno to one of the following:

- + EAGAIN Temporary error: Try again. - + EMSGSIZE Buffer is too small. - + EIO I/O error. @@ -394,20 +394,20 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { generated by the interface compiler and with code following examples in the same application.

In essence, the function performs the same operation as - , but instead of using an + ei_xreceive_msg, but instead of using an ei_x_buff, the function expects a pointer to a character - pointer (), where the character pointer - is to point to a memory area allocated by . - Argument is to be a pointer to an integer + pointer (mbufp), where the character pointer + is to point to a memory area allocated by malloc. + Argument bufsz is to be a pointer to an integer containing the exact size (in bytes) of the memory area. The function may reallocate the memory area and will in such cases put the new - size in and update - .

+ size in *bufsz and update + *mbufp.

Returns either ERL_TICK or the - field of the - . The length - of the message is put in . On error - a value is returned.

+ msgtype field of the + erlang_msg *msg. The length + of the message is put in *msglen. On error + a value < 0 is returned.

It is recommended to use ei_xreceive_msg instead when possible, for the sake of readability. However, the function will be retained in the interface for compatibility and @@ -432,23 +432,23 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { intei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x) Receive a message. -

Receives a message to the buffer in . - allows the buffer in - to grow, but +

Receives a message to the buffer in x. + ei_xreceive_msg allows the buffer in + x to grow, but ei_receive_msg fails if the message is larger than the pre-allocated buffer in - .

+ x.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is a pointer to an - structure + msg is a pointer to an + erlang_msg structure and contains information on the message received. - is buffer obtained from - . + x is buffer obtained from + ei_x_new. -

On success, the functions return and the - struct is initialized. - is defined as follows:

+

On success, the functions return ERL_MSG and the + msg struct is initialized. + erlang_msg is defined as follows:

-

identifies the type of message, and is +

msgtype identifies the type of message, and is one of the following:

- + ERL_SEND

Indicates that an ordinary send operation has occurred. - to]]> contains the pid of the recipient (the + msg->to contains the pid of the recipient (the C-node).

 - + ERL_REG_SEND

A registered send operation occurred. - from]]> contains the pid of the sender.

+ msg->from contains the pid of the sender.

 - or - + ERL_LINK or + ERL_UNLINK -

to]]> and - from]]> contain the pids of the +

msg->to and + msg->from contain the pids of the sender and recipient of the link or unlink.

 - + ERL_EXIT -

Indicates a broken link. to]]> and - from]]> contain the pids of the linked +

Indicates a broken link. msg->to and + msg->from contain the pids of the linked processes.

 @@ -520,19 +520,19 @@ typedef struct {

Sends an Erlang term to a registered process.

-

is an open descriptor to an Erlang +

fd is an open descriptor to an Erlang connection.

 - is the registered name of the + server_name is the registered name of the intended recipient. - is the buffer containing the term in + buf is the buffer containing the term in binary format. - is the length of the message in bytes. + len is the length of the message in bytes.

Returns 0 if successful, otherwise -1. In - the latter case it sets to - .

+ the latter case it sets erl_errno to + EIO.

Example:

Send the atom "ok" to the process "worker":

Remote Procedure Call from C to Erlang.

Supports calling Erlang functions on remote nodes. - sends an RPC request to a remote node - and receives the results of such a - call. combines the functionality of these + ei_rpc_to() sends an RPC request to a remote node + and ei_rpc_from() receives the results of such a + call. ei_rpc() combines the functionality of these two functions by sending an RPC request and waiting for the results. See also rpc:call/4 in Kernel.

-

is the C-node structure previously - initiated by a call to or - .

+

ec is the C-node structure previously + initiated by a call to ei_connect_init() or + ei_connect_xinit().

 -

is an open descriptor to an Erlang +

fd is an open descriptor to an Erlang connection.

 -

is the maximum time (in milliseconds) - to wait for results. Specify to +

timeout is the maximum time (in milliseconds) + to wait for results. Specify ERL_NO_TIMEOUT to wait forever. - waits infinitely for the answer, + ei_rpc() waits infinitely for the answer, that is, the call will never time out.

 -

is the name of the module containing the +

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

 -

is the name of the function to run.

+

fun is the name of the function to run.

 -

is a pointer to a buffer with an +

argbuf is a pointer to a buffer with an encoded Erlang list, without a version magic number, containing the arguments to be passed to the function.

 -

is the length of the buffer +

argbuflen is the length of the buffer containing the encoded Erlang list.

 -

is structure of type - and contains information on the +

msg is structure of type + erlang_msg and contains information on the message - received. For a description of the + received. For a description of the erlang_msg format, see ei_receive_msg.

 -

points to the dynamic buffer that receives - the result. For this is the result +

x points to the dynamic buffer that receives + the result. For ei_rpc() this is the result without the version magic number. For - the result returns a version - magic number and a 2-tuple .

+ ei_rpc_from() the result returns a version + magic number and a 2-tuple {rex,Reply}.

 -

returns the number of bytes in the +

ei_rpc() returns the number of bytes in the result on success and -1 on failure. - returns the - number of bytes, otherwise one of , - , - and . When failing, all three - functions set to one of the + ei_rpc_from() returns the + number of bytes, otherwise one of ERL_TICK, + ERL_TIMEOUT, + and ERL_ERROR. When failing, all three + functions set erl_errno to one of the following:

- + EIO I/O error. - + ETIMEDOUT Time-out expired. - + EAGAIN Temporary error: Try again.

Example:

@@ -662,11 +662,11 @@ if (ei_decode_version(result.buff, &index) < 0 Retrieve the pid of the C-node.

Retrieves the pid of the C-node. Every C-node - has a (pseudo) pid used in , - , - and others. This is contained in a field in the + has a (pseudo) pid used in ei_send_reg, + ei_rpc, + and others. This is contained in a field in the ec structure. It will be safe for a long time to fetch this - field directly from the structure.

+ field directly from the ei_cnode structure.

 @@ -676,18 +676,18 @@ if (ei_decode_version(result.buff, &index) < 0

Sends an Erlang term to a process.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is the pid of the intended recipient of + to is the pid of the intended recipient of the message. - is the buffer containing the term in + buf is the buffer containing the term in binary format. - is the length of the message in bytes. + len is the length of the message in bytes.

Returns 0 if successful, otherwise -1. In - the latter case it sets to - .

+ the latter case it sets erl_errno to + EIO.

 @@ -720,14 +720,14 @@ if (ei_decode_version(result.buff, &index) < 0

This function is retained for compatibility with code generated by the interface compiler and with code following examples in the same application.

-

The function works as with one - exception. Instead of taking as first +

The function works as ei_reg_send with one + exception. Instead of taking ei_cnode as first argument, it takes a second argument, an - , + erlang_pid, which is to be the process identifier of the sending process (in the Erlang distribution protocol).

-

A suitable can be constructed from the - structure by the following example +

A suitable erlang_pid can be constructed from the + ei_cnode structure by the following example code:

num = fd;

Can be used to retrieve information about the C-node. These values are initially set with - or - .

+ ei_connect_init() or + ei_connect_xinit().

These function simply fetch the appropriate field from the - + ec structure. Read the field directly will probably be safe for a long time, so these functions are not really needed.

 @@ -788,16 +788,16 @@ self->num = fd; -relaxed_command_check, which it normally is not.

To unregister a node you have published, you should close the descriptor that was returned by - .

+ ei_publish().

This function is deprecated and will be removed in a future release.

 -

is the node structure of the node to +

ec is the node structure of the node to unregister.

If the node was successfully unregistered from EPMD, the function returns 0. Otherwise, -1 is returned and - is set to .

+ erl_errno is set to EIO.

 @@ -818,18 +818,18 @@ self->num = fd;

If a connection attempt fails, the following can be checked:

- . + erl_errno. That the correct cookie was used That EPMD is running That the remote Erlang node on the other side is running the - same version of Erlang as the library - That environment variable + same version of Erlang as the ei library + That environment variable ERL_EPMD_PORT is set correctly

The connection attempt can be traced by setting a trace level by either - using or by setting environment - variable . + using ei_set_tracelevel or by setting environment + variable EI_TRACELEVEL. The trace levels have the following messages:

-- cgit v1.2.3