From 031f9ca91ade7fbb9e31c82545401b8a5531e539 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Thu, 20 Oct 2016 11:46:03 +0200 Subject: erl_interface: Editorial changes --- lib/erl_interface/doc/src/erl_connect.xml | 546 +++++++++++++++++------------- 1 file changed, 318 insertions(+), 228 deletions(-) (limited to 'lib/erl_interface/doc/src/erl_connect.xml') diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index 0799e30905..a027cb0a84 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -28,27 +28,30 @@ Bjarne Däcker Torbjörn Törnkvist - 980703 + 1998-07-03 A erl_connect.xml erl_connect - Communicate with Distributed Erlang + Communicate with distributed Erlang.

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

-

A C node appears to Erlang as a - hidden node. + +

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 .

+ C-node can communicate with it in a normal manner, but + the node name does not appear in the listing provided by + erlang:nodes/0 + in ERTS.

 + interl_accept(listensock, conp) Accept a connection. + int listensock; ErlConnect *conp; @@ -56,10 +59,12 @@

This function is used by a server process to accept a connection from a client process.

-

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

-

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

+ + is an open socket descriptor on + which has previously been called. + is a pointer to an + struct, described as follows: + is set to .

 + interl_close_connection(fd) Close a connection to an Erlang node. @@ -79,47 +85,54 @@ typedef struct { int fd; -

This function closes an open connection to an Erlang node.

+

Closes an open connection to an Erlang node.

is a file descriptor obtained from - or .

-

On success, 0 is returned. If the call fails, a non-zero value - is returned, and the reason for - the error can be obtained with the appropriate platform-dependent - call.

+ or + .

+

Returns 0 on success. If the call fails, a non-zero value + is returned, and the reason for the error can be obtained with the + appropriate platform-dependent call.

 + interl_connect(node) interl_xconnect(addr, alive) - Establishe a connection to an Erlang node. + Establish a connection to an Erlang node. char *node, *alive; struct in_addr *addr; -

These functions set up a connection to an Erlang node.

-

requires the IP address of the remote - host and the alive name of the remote node - to be specified. provides an alternative +

Sets up a connection to an Erlang node.

+

requires the IP address of the + remote host and the alivename of the remote node to be + specified. provides an alternative interface, and determines the information from the node name provided.

-

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

-

is the alivename of the remote 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 to one of:

+ + is the 32-bit IP address of the remote + host. + is the alivename of the remote node. + + is the name of the remote node. + +

Returns an open file descriptor on success, otherwise a negative + value. In the latter case is set to one + of:

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

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

+

Also, values from + (2) and + (2) + system calls can be propagated into .

+

Example:

 + interl_connect_init(number, cookie, creation) interl_connect_xinit(host, alive, node, addr, cookie, creation) Initialize communication. + int number; char *cookie; @@ -147,47 +162,72 @@ erl_xconnect( &addr , ALIVE ); struct in_addr *addr; -

These functions initialize the - module. In particular, they are used to identify the name of the +

Initializes the module. + In particular, these functions 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 + be called before any of the other functions in the erl_connect module are used.

-

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

-

If you use 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 - instead. -

-

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

-

is the alivename of the node.

-

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

-

is the 32-bit IP address of .

-

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

-

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 +

stores for later use + information about:

+ + Hostname of the node, + Alivename, + Node name, + IP address, + Cookie, + Creation number, + +

+ provides an alternative interface that does not require as much + information from the caller. Instead, + + uses to obtain default values.

+

If you use , your node will + have a short name, that is, it will not be fully qualified. If you + need to use fully qualified (long) names, use + instead.

+ + +

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

+ + +

is the alivename of the node.

+ + +

is the node name. It is to + be of the form alivename@hostname.

+ + +

is the 32-bit IP address of + .

+ + +

is the authorization string required + for access to the remote node. If NULL, the user + HOME directory is searched for a cookie file + . The path to + the home directory is retrieved from environment variable + on Unix and from the + and + variables on Windows. For more + details, see the + kernel:auth module.

+ + +

helps identifying 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 is assigned a creation number when it calls .

-

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

-

Example 1:

+

is used by + to + construct the actual node name. In Example 2 + below, "c17@a.DNS.name" is the resulting node name.

+

Example 1:

when initializing !"); ]]> -

Example 2:

+

Example 2:

when initializing !"); ]]> + interl_publish(port) Publish a node name. @@ -213,66 +254,74 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) int port; -

These functions are used by a server process to register +

This function is 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 and on an open socket.

-

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. -

-

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

+ Before calling this function, the process should + have called and + on an open socket.

+

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

+

To unregister with EPMD, simply close the returned descriptor.

+

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

- I/O error + I/O error. -

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

+

Also, values from + (2) + and (2) system calls can be + propagated into .

 + interl_receive(fd, bufp, bufsize) Receive a message. + int fd; char *bufp; int bufsize; -

This function receives a message consisting of a sequence +

Receives a message consisting of a sequence of bytes in the Erlang external format.

-

is an open descriptor to an Erlang connection.

-

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

-

indicates the size of .

-

If a tick occurs, i.e., the Erlang node on the + + is an open descriptor to an Erlang + connection. + is a buffer large enough to hold the + expected message. + indicates the size of + . + +

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 will return and - no message will be placed in the buffer. Also, - will be set to .

+ is still alive, the function returns and + no message is placed in the buffer. Also, + is set to .

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 + failure, the function returns a negative value and sets to one of:

Temporary error: Try again. - Buffer too small. + Buffer is too small. I/O error. + interl_receive_msg(fd, bufp, bufsize, emsg) - Receive and decodes a message. + Receive and decode a message. + int fd; unsigned char *bufp; @@ -280,14 +329,20 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) ErlMessage *emsg; -

This function receives the message into the specified buffer, - and decodes into the .

-

is an open descriptor to an Erlang connection.

-

is a buffer large enough to hold the expected message.

-

indicates the size of .

-

is a pointer to an structure, - into which the message will be decoded. is - defined as follows:

+

Receives the message into the specified buffer + and decodes into .

+ + is an open descriptor to an Erlang + connection. + is a buffer large enough to hold the + expected message. + indicates the size of + . + > is a pointer to an + structure + into which the message will be decoded. + is defined as follows: +

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

+ earlier versions of Erl_Interface.

 -

identifies the type of message, one of - , , , - and . -

-

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

-

If contains one of or - , then to]]> and from]]> - contain the pids of the sender and recipient of the link or unlink. - msg]]> is not used in these cases. -

-

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

+

identifies the type of message, one of the + following:

+ + + +

An ordinary send operation has occurred and + to]]> contains the pid of the recipient. + The message is in msg]]>.

+ + + +

A registered send operation has occurred and + from]]> contains the pid of the sender. + The message is in msg]]>.

+ + or + + +

to]]> and from]]> + contain the pids of the sender and recipient of the link or + unlink. msg]]> is not used.

+ + + +

A link is broken. to]]> and + from]]> contain the pids of the linked + processes, and msg]]> contains the reason + for the exit.

+ +

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

 -

If a tick occurs, i.e., the Erlang node on the +

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 will return + is still alive, the function returns 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 again.

+ but no message is placed in the buffer. In this case you + are to call again.

On success, the function returns and the - struct will be initialized as described above, or + struct is initialized as described above, or , in which case no message is returned. On - failure, the function returns and will set + failure, the function returns and sets to one of:

- Buffer too small. + Buffer is too small. - No more memory available. + No more memory is available. I/O error. + interl_reg_send(fd, to, msg) Send a message to a registered name. + int fd; char *to; ETERM *msg; -

This function sends an Erlang term to a registered process.

-

is an open descriptor to an Erlang connection.

-

is a string containing the registered name of - the intended recipient of the message.

-

is the Erlang term to be sent.

-

The function returns 1 if successful, otherwise 0 --- in - which case it will set to one of:

+

Sends an Erlang term to a registered process.

+ + is an open descriptor to an Erlang + connection. + is a string containing the registered name + of the intended recipient of the message. + is the Erlang term to be sent. + +

Returns 1 on success, otherwise 0. In + the latter case is set to one of:

- No more memory available. + No more memory is available. I/O error. + ETERM *erl_rpc(fd, mod, fun, args) interl_rpc_from(fd, timeout, emsg) @@ -386,81 +455,97 @@ typedef struct { ErlMessage *emsg; -

These functions support 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 two functions - by sending an rpc request and waiting for the results. See also - .

-

is an open descriptor to an Erlang connection.

-

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

-

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

-

is the name of the function to run.

-

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

-

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

-

The actual message returned by the rpc server - is a 2-tuple . If you are using - in your code then this is the message you - will need to parse. If you are using then the +

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 two functions by sending an RPC request and waiting for the + results. See also + rpc:call/4 in Kernel.

+ + is an open descriptor to an Erlang + connection. + is the maximum time (in milliseconds) + to wait for + results. To wait forever, specify . + When erl_rpc() calls erl_rpc_from(), the call will + never timeout. + is the name of the module containing the + function to be run on the remote node. + is the name of the function to run. + + is an Erlang list, containing the + arguments to be passed to the function. + is a message containing the result of + the function call. + +

The actual message returned by the RPC server + is a 2-tuple . If you use + in your code, this is the message + you will need to parse. If you use , the tuple itself is parsed for you, and the message returned to your - program is the erlang term containing only. Replies - to rpc requests are always ERL_SEND messages. -

+ program is the Erlang term containing only. + Replies to RPC requests are always ERL_SEND messages.

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

+ structure and the memory pointed to by + msg]]> and to]]>.

 -

returns the remote function's return value (or - if it failed). returns 0 on - success, and a negative number on failure. - returns when successful (with now - containing the reply tuple), and one of , - and otherwise. When failing, +

returns the remote function's return + value on success, otherwise .

+

returns 0 on + success, otherwise a negative number.

+

returns + on success (with now + containing the reply tuple), otherwise one of + , , or + .

+

When failing, all three functions set to one of:

- No more memory available. + No more memory is available. I/O error. - Timeout expired. + Timeout has expired. Temporary error: Try again. + interl_send(fd, to, msg) Send a message. + int fd; ETERM *to, *msg; -

This function sends an Erlang term to a process.

-

is an open descriptor to an Erlang connection.

-

is an Erlang term containing the Pid of the - intended recipient of the message.

-

is the Erlang term to be sent.

-

The function returns 1 if successful, otherwise 0 --- in - which case it will set to one of:

+

Sends an Erlang term to a process.

+ + is an open descriptor to an Erlang + connection. + is an Erlang term containing the pid of + the intended recipient of the message. + > is the Erlang term to be sent. + +

Returns 1 on success, otherwise 0. In + the latter case is set to one of:

- Invalid argument: is not a valid Erlang pid. + Invalid argument: is not a valid Erlang + pid. - No more memory available. + No more memory is available. I/O error. + const char *erl_thisalivename() const char *erl_thiscookie() @@ -469,11 +554,13 @@ typedef struct { const char *erl_thisnodename() Retrieve some values. -

These functions can be used to retrieve information about - the C Node. These values are initially set with - or .

+

Retrieves information about + the C-node. These values are initially set with + or + .

 + interl_unpublish(alive) Forcefully unpublish a node name. @@ -482,28 +569,28 @@ typedef struct {

This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check - flag, which it normally isn't.

- -

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

- + specified node from EPMD on the local host. This is, however, usually + not allowed, unless EPMD was started with flag + -relaxed_command_check, which it normally is not.

+

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

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

+ release.

 -

is the name of the node to unregister, i.e., the - first component of the nodename, without the .

-

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

+

is the name of the node to unregister, that + is, the first component of the node name, without + .

+

If the node was successfully unregistered from EPMD, 0 is + returned, otherwise -1 is returned and + is set to .

 + interl_xreceive_msg(fd, bufpp, bufsizep, emsg) - Receive and decodes a message. + Receive and decode a message. int fd; unsigned char **bufpp; @@ -511,33 +598,35 @@ typedef struct { ErlMessage *emsg; -

This function is similar to . The - difference is that expects the buffer to - have been allocated by , 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. -

+

Similar to . The difference is + that expects the buffer to + have been allocated by , and reallocates it + if the received + message does not fit into the original buffer. Therefore + both buffer and buffer length are given as pointers; their values + can change by the call.

On success, the function returns and the - struct will be initialized as described above, or + struct is initialized as described above, or , in which case no message is returned. On - failure, the function returns and will set + failure, the function returns and sets to one of:

- Buffer too small. + Buffer is too small. - No more memory available. + No more memory is available. I/O error. + struct hostent*erl_gethostbyaddr(addr, length, type) struct hostent*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop) struct hostent*erl_gethostbyname(name) struct hostent*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop) + Name lookup functions. const char *name; @@ -550,7 +639,7 @@ typedef struct { int *h_errnop; -

These are convenience functions for some common name lookup functions.

+

Convenience functions for some common name lookup functions.

 @@ -558,12 +647,13 @@ typedef struct {
Debug Information

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

+ - that the right cookie was used - that epmd is running - the remote Erlang node on the other side is running the same - version of Erlang as the library. + 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
-- cgit v1.2.3