20022023
Ericsson AB. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Erl_Interface User's Guide
Kent Boortz
Kent Boortz
ei_users_guide.xml
Introduction
The Erl_Interface library contains functions that help you
integrate programs written in C and Erlang. The functions in
Erl_Interface support the following:
- Manipulation of data represented as Erlang data types
- Conversion of data between C and Erlang formats
- Encoding and decoding of Erlang data types for transmission or
storage
- Communication between C nodes and Erlang processes
- Backup and restore of C node state to and from
Mnesia
By default, the Erl_Interface library is only guaranteed
to be compatible with other Erlang/OTP components from the same
release as the libraries themselves. For information about how to
communicate with Erlang/OTP components from earlier releases, see
function
ei_set_compat_rel.
Scope
In the following sections, these topics are described:
- Compiling your code for use with Erl_Interface
- Initializing Erl_Interface
- Encoding, decoding, and sending Erlang terms
- Building terms and patterns
- Pattern matching
- Connecting to a distributed Erlang node
- Using the Erlang Port Mapper Daemon (EPMD)
- Sending and receiving Erlang messages
- Remote procedure calls
- Using global names
Prerequisites
It is assumed that the reader is familiar with the Erlang programming
language.
Compiling and Linking Your Code
To use any of the Erl_Interface functions, include the
following line in your code:
Determine where the top directory of your OTP installation is.
To find this, start Erlang and enter the following
command at the Eshell prompt:
code:root_dir().
/usr/local/otp ]]>
To compile your code, ensure that your C compiler knows where
to find ei.h by specifying an appropriate
-I argument on the command line, or add it to
the CFLAGS definition in your
Makefile. The correct value for this path is
$OTPROOT/lib/erl_interface-$EIVSN/include,
where:
-
$OTPROOT is the path reported by
code:root_dir/0 in the example above.
-
$EIVSN is the version of the Erl_Interface application,
for example, erl_interface-3.2.3.
Compiling the code:
When linking:
- Specify the path to libei.a with
-L$OTPROOT/lib/erl_interface-3.2.3/lib.
- Specify the name of the library with -lei.
Do this on the command line or add the flags to the
LDFLAGS definition in your
Makefile.
Linking the code:
On some systems it can be necessary to link with some more
libraries (for example, libnsl.a and
libsocket.a on Solaris, or
wsock32.lib on Windows) to use the
communication facilities of Erl_Interface.
If you use the Erl_Interface functions in a threaded
application based on POSIX threads or Solaris threads, then
Erl_Interface needs access to some of the synchronization
facilities in your threads package. You must specify extra
compiler flags to indicate which of the packages you use. Define
_REENTRANT and either STHREADS or
PTHREADS. The default is to use POSIX threads if
_REENTRANT is specified.
Initializing the Library
Before calling any of the other functions in the library,
initialize it by calling
ei_init() exactly once.
Encoding, Decoding, and Sending Erlang Terms
Data sent between distributed Erlang nodes is encoded in the
Erlang external format. You must therefore encode and decode
Erlang terms into byte streams if you want to use the distribution
protocol to communicate between a C program and Erlang.
The Erl_Interface library supports this activity. It has
several C functions that create and manipulate Erlang data
structures. The following example shows how to create and encode
an Erlang tuple {tobbe,3928}:
For a complete description, see the
ei module.
Building Terms
The previous example can be simplified by using the
ei_x_format_wo_ver function
to create an Erlang term:
For a complete description of the different format directives, see the
the ei_x_format_wo_ver function.
The following example is more complex:
As in the previous examples, it is your responsibility to free the
memory allocated for Erlang terms. In this example,
ei_x_free() ensures that the data
pointed to by buf is released.
Connecting to a Distributed Erlang Node
To connect to a distributed Erlang node, you must first
initialize the connection routine with one of the
ei_connect_init_* functions,
which stores information, such as the hostname, and node name
for later use:
For more information, see the
ei_connect module.
After initialization, you set up the connection to the Erlang node.
To specify the Erlang node you want to connect to, use the
ei_connect_*() family of functions. The following example sets up the
connection and is to result in a valid socket file descriptor:
Using EPMD
erts:epmd
is the Erlang Port Mapper Daemon. Distributed
Erlang nodes register with epmd on the local host to
indicate to other nodes that they exist and can accept connections.
epmd maintains a register of
node and port number information, and when a node wishes to connect to
another node, it first contacts epmd to find the
correct port number to connect to.
When you use
ei_connect
to connect to an Erlang node, a connection is first made to
epmd and, if the node is known, a
connection is then made to the Erlang node.
C nodes can also register themselves with epmd
if they want other
nodes in the system to be able to find and connect to them.
Before registering with epmd, you must first
create a listen socket and bind it to a port. Then:
pub is a file descriptor now connected to
epmd. epmd
monitors the other end of the connection. If it detects that the
connection has been closed, the node becomes unregistered. So, if you
explicitly close the descriptor or if your node fails, it becomes
unregistered from epmd.
Notice that on some systems a failed node is
not detected by this mechanism, as the operating system does not
automatically close descriptors that were left open when the node
failed. If a node has failed in this way, epmd
prevents you from
registering a new node with the old name, as it thinks that the old
name is still in use. In this case, you must close the port
explicitly
Sending and Receiving Erlang Messages
Use one of the following two functions to send messages:
-
ei_send
-
ei_reg_send
As in Erlang, messages can be sent to a
pid or to a registered name. It is easier to send a
message to a registered name, as it avoids the problem of finding
a suitable pid.
Use one of the following two functions to receive messages:
-
ei_receive
-
ei_receive_msg
Example of Sending Messages
In the following example, {Pid, hello_world} is
sent to a registered process my_server:
The first element of the tuple that is sent is your own
pid. This enables my_server to reply.
For more information about the primitives, see the
ei_connect module.
Example of Receiving Messages
In this example, {Pid, Something} is received.
To provide robustness, a distributed Erlang node
occasionally polls all its connected neighbors in an attempt to
detect failed nodes or communication links. A node that receives such
a message is expected to respond immediately with an
ERL_TICK message. This is done automatically by
ei_xreceive_msg(). However, when this has occurred,
ei_xreceive_msg returns ERL_TICK to
the caller without storing a message into the
erlang_msg structure.
When a message has been received, it is the caller's responsibility
to free the received message.
For more information, see the
ei_connect and
ei modules.
Remote Procedure Calls
An Erlang node acting as a client to another Erlang node
typically sends a request and waits for a reply. Such a request is
included in a function call at a remote node and is called a remote
procedure call.
The following example checks if a specific Erlang process is alive:
For more information about ei_rpc() and its
companions ei_rpc_to() and
ei_rpc_from(), see the
ei_connect module.
Using Global Names
A C node has access to names registered through the
global
module in Kernel. Names can be looked up, allowing the C node to send messages
to named Erlang services. C nodes can also register global names,
allowing them to provide named services to Erlang processes or other C
nodes.
Erl_Interface does not provide a native implementation of the
global service. Instead it uses the global services provided by a "nearby"
Erlang node. To use the services described in this section,
it is necessary to first open a connection to an Erlang node.
To see what names there are:
ei_global_names
allocates and returns a buffer containing
all the names known to the global module in Kernel.
count is initialized to
indicate the number of names in the array. The array of strings in names
is terminated by a NULL pointer, so it is not necessary to use
count to determine when the last name is reached.
It is the caller's responsibility to free the array.
ei_global_names allocates the array and all the strings
using a single call to malloc(), so
free(names) is all that is necessary.
To look up one of the names:
If "schedule" is known to the
global module in Kernel, an Erlang pid is
written to the_pid. This pid that can be used to send messages to the schedule service.
Also, node is initialized to contain the name of
the node where the service is registered, so that you can make a
connection to it by simply passing the variable to
ei_connect.
Before registering a name, you should already have registered your
port number with epmd. This is not strictly necessary,
but if you
neglect to do so, then other nodes wishing to communicate with your
service cannot find or connect to your process.
Create a name that Erlang processes can use to communicate with your
service:
After registering the name, use
ei_accept
to wait for incoming connections.
Remember to free pid later with
ei_x_free.
To unregister a name: