From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/erl_interface/doc/src/ei_connect.xml | 639 +++++++++++++++++++++++++++++++ 1 file changed, 639 insertions(+) create mode 100644 lib/erl_interface/doc/src/ei_connect.xml (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 new file mode 100644 index 0000000000..08e7b122c6 --- /dev/null +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -0,0 +1,639 @@ + + + + +
+ + 20012009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ei_connect + Jakob Cederlund + + ? + ? + 2001-09-01 + A + ei_connect.sgml +
+ ei_connect + Communicate with distributed erlang + +

This module enables C programs to communicate with erlang nodes, + using the erlang distribution over TCP/IP.

+

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 .

+

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

+ + +
+ Timeout functions +

Most functions appear in a version with the suffix + appended to the function name. Those function take + an additional argument, a timeout 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 will return an error and + will be set to . With + communication primitive is ment an operation on the socket, like + , , or .

+

Obviously the timeouts are for implementing fault tolerance, + not to keep hard realtime promises. The functions + are for detecting non-responsive peers and to avoid blocking on + socket operations.

+

A timeout value of (zero), means that timeouts are + disabled. Calling a -function with the last argument as + is therefore exactly the same thing as calling the + function without the suffix.

+

As with all other ei functions, you are not expected + to put the socket in non blocking mode yourself in the program. Every + use of non blocking mode is embedded inside the timeout + functions. The socket will always be back in blocking mode after + the operations are completed (regardless of the result). To + avoid problems, leave the socket options alone. Ei will handle + any socket options that need modification.

+

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

+
+ + + intei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation) + 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. + +

These function initializes the structure, to + identify the node name and cookie of the server. One of them + has to be called before other functions that works on the + type or a file descriptor associated with a + connection to another node are used.

+

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

+

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

+

is the cookie for the node.

+

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're running + on. If long names are to be used, it should be fully + qualified (i.e. instead of + ).

+

is the registered name of the process.

+

is the full name of the node, + i.e. .

+

if the IP address of the host.

+

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

+

A connection is closed by simply closing the socket. Refer + to system documentation to close the socket gracefully (when + there are outgoing packets before close).

+

This function return a negative value indicating that an error + occurred.

+

Example 1: +

+ +

Example 2: +

+ + + + + intei_connect(ei_cnode* ec, char *nodename) + intei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename) + Establishe a connection to an Erlang node + +

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 + 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:

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

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

+

Example:

+ + + + + intei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms) + intei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms) + Establish a connection to an Erlang node with optional timeout + +

ei_connect and ei_xconnect with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_receive(int fd, unsigned char* bufp, int bufsize) + Receive a message + +

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

+

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

+

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

+

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 will set + to one of:

+ + + Temporary error: Try again. + + Buffer too small. + + I/O error. + + + + + intei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms) + Receive a message with optional timeout + +

ei_receive with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x) + intei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x) + Receive a message + +

These functions receives a message to the buffer in + . allows the buffer in + to grow, but fails if the + message is bigger than the preallocated buffer in .

+

is an open descriptor to an Erlang connection.

+

is a pointer to an structure + and contains information on the message received.

+

is buffer obtained from .

+

On success, the function returns and the + struct will be initialized. + is defined as follows:

+ +

identifies the type of message, and is one of + , , , + and .

+

If is this indicates that an + ordinary send operation has taken place, and to]]> + contains the Pid of the recipient (the C-node). If + is then a registered send + operation took place, and from]]> contains the Pid + of the sender.

+

If is or , then + to]]> and from]]> contain the pids of the + sender and recipient of the link or unlink.

+

If is , then this indicates that + a link has been broken. In this case, to]]> and + from]]> contain the pids of the linked processes.

+

The return value is the same as for , see + above.

+ + + + intei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms) + intei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms) + Receive a message with optional timeout + +

ei_receive_msg and ei_xreceive_msg with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen) + Obsolete function for receiving a message + +

This function is retained for compatibility with code + 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_x_buff, the + function expects a pointer to a character pointer + (), where the character pointer should point to a + memory area allocated by . The argument + should 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 .

+

Furthermore the function returns either ERL_TICK or the + field of the . The actual + length of the message is put in . On error it + will return a value .

+

It is recommended to use ei_xreceive_msg instead when + possible, for the sake of readability. The function will + however be retained in the interface for compatibility and + will not be removed not be removed in future releases + without notice.

+ + + + intei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms) + Obsolete function for receiving a message with timeout + +

ei_receive_encoded with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_send(int fd, erlang_pid* to, char* buf, int len) + Send a message + +

This function sends an Erlang term to a process.

+

is an open descriptor to an Erlang connection.

+

is the Pid of the intended recipient of the + message.

+

is the buffer containing the term in binary + format.

+

is the length of the message in bytes.

+

The function returns 0 if successful, otherwise -1, in the + latter case it will set to .

+ + + + intei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) + Send a message with optional timeout + +

ei_send with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_send_encoded(int fd, erlang_pid* to, char* buf, int len) + Obsolete function to send a message + +

Works exactly as ei_send, the alternative name retained for + backward compatibility. The function will not be + removed without notice.

+ + + + intei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) + Obsolete function to send a message with optional timeout + +

ei_send_encoded with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len) + Send a message to a registered name + +

This function sends an Erlang term to a registered process. +

+

This function sends an Erlang term to a process.

+

is an open descriptor to an Erlang connection.

+

is the registered name of the intended + recipient.

+

is the buffer containing the term in binary + format.

+

is the length of the message in bytes.

+

The function returns 0 if successful, otherwise -1, in the + latter case it will set to .

+

Example, send the atom "ok" to the process "worker":

+ + + + + intei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms) + Send a message to a registered name with optional timeout + +

ei_reg_send with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len) + Obsolete function to send a message to a registered name + +

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 the as a first + argument, it takes a second argument, an + which should 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 code:

+ num = fd; + ]]> + + + + intei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len) + Obsolete function to send a message to a registered name with timeout + +

ei_send_reg_encoded with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x) + intei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen) + intei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x) + Remote Procedure Call from C to Erlang + +

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 the C-node structure previously initiated by a + call to or +

+

is an open descriptor to an Erlang connection.

+

is the maximum time (in ms) to wait for + results. Specify to wait forever. + will wait infinitely for the answer, + i.e. the call will never time out.

+

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 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 containing the + encoded Erlang list.

+

structure of type and contains + information on the message received. See + for a description of the format.

+

points to the dynamic buffer that receives the + result. For for this will be the result + without the version magic number. For + the result will return a version magic number and a 2-tuple + .

+

returns the number of bytes in the result + on success and -1 on failure. returns + number of bytes or one of , + and otherwise. When failing, + all three functions set to one of:

+ + + I/O error. + + Timeout expired. + + Temporary error: Try again. + +

Example, check to see if an erlang process is alive:

+ + + + + intei_publish(ei_cnode *ec, int port) + Publish a node name + +

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

+

is the C-node structure.

+

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

+

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

+

To unregister with epmd, simply close the returned + descriptor. See also .

+

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

+

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

+ + + + intei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms) + Publish a node name with optional timeout + +

ei_publish with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_accept(ei_cnode *ec, int listensock, ErlConnect *conp) + Accept a connection from another node + +

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

+

is the C-node structure.

+

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

+

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

+ +

On success, 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 .

+ + + + intei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms) + Accept a connection from another node with optional timeout + +

ei_accept with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_unpublish(ei_cnode *ec) + Unpublish a node name + +

This function can be called by a process to unregister a + specified node 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 .

+ +

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

+ +

is the node structure of the node to unregister.

+

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

+ + + + intei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms) + Unpublish a node name with optional timeout + +

ei_unpublish with an optional timeout argument, + see the description at the beginning of this document.

+ + + + const char *ei_thisnodename(ei_cnode *ec) + const char *ei_thishostname(ei_cnode *ec) + const char *ei_thisalivename(ei_cnode *ec) + Retrieve some values + +

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

+

They simply fetches the appropriate field from the + structure. Read the field directly will probably be safe for + a long time, so these functions are not really needed.

+ + + + erlang_pid *ei_self(ei_cnode *ec) + Retrieve the Pid of the C-node + +

This function 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 + structure. It will be safe for a long time to fetch this + field directly from the structure.

+ + + + struct hostent*ei_gethostbyname(const char *name) + struct hostent*ei_gethostbyaddr(const char *addr, int len, int type) + struct hostent*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop) + struct hostent*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop) + Name lookup functions + +

These are convenience functions for some common name lookup functions.

+ + + + +
+ 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. + the environment variable + is set correctly. + +
+ + -- cgit v1.2.3