<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2002</year><year>2020</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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.

    </legalnotice>

    <title>Erl_Interface User's Guide</title>
    <prepared>Kent Boortz</prepared>
    <responsible>Kent Boortz</responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date></date>
    <rev></rev>
    <file>ei_users_guide.xml</file>
  </header>

  <section>
    <title>Introduction</title>
    <p>The <c>Erl_Interface</c> library contains functions that help you
      integrate programs written in C and Erlang. The functions in
      <c>Erl_Interface</c> support the following:</p>
    <list type="bulleted">
      <item>Manipulation of data represented as Erlang data types</item>
      <item>Conversion of data between C and Erlang formats</item>
      <item>Encoding and decoding of Erlang data types for transmission or
        storage</item>
      <item>Communication between C nodes and Erlang processes</item>
      <item>Backup and restore of C node state to and from
        <seeerl marker="mnesia:mnesia">Mnesia</seeerl></item>
    </list>
    <note>
      <p>By default, the <c>Erl_Interface</c> 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 <seecref marker="ei#ei_set_compat_rel">
        <c>ei_set_compat_rel</c></seecref>.</p>
    </note>

    <section>
      <title>Scope</title>
      <p>In the following sections, these topics are described:</p>
      <list type="bulleted">
        <item>Compiling your code for use with <c>Erl_Interface</c></item>
        <item>Initializing <c>Erl_Interface</c></item>
        <item>Encoding, decoding, and sending Erlang terms</item>
        <item>Building terms and patterns</item>
        <item>Pattern matching</item>
        <item>Connecting to a distributed Erlang node</item>
        <item>Using the Erlang Port Mapper Daemon (EPMD)</item>
        <item>Sending and receiving Erlang messages</item>
        <item>Remote procedure calls</item>
        <item>Using global names</item>
        <item>Using the registry</item>
      </list>
    </section>

    <section>
      <title>Prerequisites</title>
      <p>It is assumed that the reader is familiar with the Erlang programming
        language.</p>
    </section>
  </section>

  <section>
    <title>Compiling and Linking Your Code</title>
    <p>To use any of the <c>Erl_Interface</c> functions, include the
      following line in your code:</p>

    <code type="none"><![CDATA[
#include "ei.h"    ]]></code>

    <p>Determine where the top directory of your OTP installation is.
      To find this, start Erlang and enter the following
      command at the Eshell prompt:</p>

    <code type="none"><![CDATA[
Eshell V4.7.4  (abort with ^G)
1> code:root_dir().
/usr/local/otp    ]]></code>

    <p>To compile your code, ensure that your C compiler knows where
      to find <c>ei.h</c> by specifying an appropriate
      <c>-I</c> argument on the command line, or add it to
      the <c>CFLAGS</c> definition in your
      <c>Makefile</c>. The correct value for this path is
      <c>$OTPROOT/lib/erl_interface-$EIVSN/include</c>,
      where:</p>

    <list type="bulleted">
      <item>
        <p><c>$OTPROOT</c> is the path reported by
          <c>code:root_dir/0</c> in the example above.</p>
      </item>
      <item>
        <p><c>$EIVSN</c> is the version of the <c>Erl_Interface</c> application,
          for example, <c>erl_interface-3.2.3</c>.</p>
      </item>
    </list>

    <p>Compiling the code:</p>

    <code type="none"><![CDATA[
$ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c    ]]></code>

    <p>When linking:</p>

    <list type="bulleted">
      <item>Specify the path to <c>libei.a</c> with
        <c>-L$OTPROOT/lib/erl_interface-3.2.3/lib</c>.</item>
      <item>Specify the name of the library with <c>-lei</c>.</item>
    </list>

    <p>Do this on the command line or add the flags to the
      <c>LDFLAGS</c> definition in your
      <c>Makefile</c>.</p>

    <p>Linking the code:</p>

    <code type="none"><![CDATA[
$ ld -L/usr/local/otp/lib/erl_interface-3.2.3/
                            lib myprog.o -lei -o myprog    ]]></code>

    <p>On some systems it can be necessary to link with some more
      libraries (for example, <c>libnsl.a</c> and
      <c>libsocket.a</c> on Solaris, or
      <c>wsock32.lib</c> on Windows) to use the
      communication facilities of <c>Erl_Interface</c>.</p>

    <p>If you use the <c>Erl_Interface</c> functions in a threaded
      application based on POSIX threads or Solaris threads, then
      <c>Erl_Interface</c> 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
      <c>_REENTRANT</c> and either <c>STHREADS</c> or
      <c>PTHREADS</c>. The default is to use POSIX threads if
      <c>_REENTRANT</c> is specified.</p>
  </section>

  <section>
    <title>Initializing the Library</title>
    <p>
      Before calling any of the other functions in the library,
      initialize it by calling
      <c>ei_init()</c> exactly once.
    </p>
  </section>

  <section>
    <title>Encoding, Decoding, and Sending Erlang Terms</title>
    <p>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.</p>

    <p>The <c>Erl_Interface</c> 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 <c>{tobbe,3928}</c>:</p>

    <code type="none"><![CDATA[
ei_x_buff buf;
ei_x_new(&buf);
int i = 0;
ei_x_encode_tuple_header(&buf, 2);
ei_x_encode_atom(&buf, "tobbe");
ei_x_encode_long(&buf, 3928);    ]]></code>

    <p>For a complete description, see the
    <seecref marker="ei"><c>ei</c></seecref> module.</p>
  </section>

  <section>
    <marker id="building_terms_and_patterns"/>
    <title>Building Terms</title>
    <p>The previous example can be simplified by using the
      <seecref marker="ei#ei_x_format_wo_ver"><c>ei_x_format_wo_ver</c></seecref> function
      to create an Erlang term:</p>

    <code type="none"><![CDATA[
ei_x_buff buf;
ei_x_new(&buf);
ei_x_format_wo_ver(&buf, "{~a,~i}", "tobbe", 3928);    ]]></code>

    <p>For a complete description of the different format directives, see the
      the <seecref marker="ei#ei_x_format_wo_ver"><c>ei_x_format_wo_ver</c></seecref> function.</p>

    <p>The following example is more complex:</p>

    <code type="none"><![CDATA[
ei_x_buff buf;
int i = 0;
ei_x_new(&buf);
ei_x_format_wo_ver(&buf,
                   "[{name,~a},{age,~i},{data,[{adr,~s,~i}]}]",
                   "madonna",
                   21,
                  "E-street", 42);
ei_print_term(stdout, buf.buff, &i);
ei_x_free(&buf);      ]]></code>

    <p>As in the previous examples, it is your responsibility to free the
      memory allocated for Erlang terms. In this example,
      <c>ei_x_free()</c> ensures that the data
      pointed to by <c>buf</c> is released.</p>

  </section>

  <section>
    <title>Connecting to a Distributed Erlang Node</title>
    <p>To connect to a distributed Erlang node, you must first
      initialize the connection routine with one of the
      <seecref marker="ei_connect#ei_connect_init">
      <c>ei_connect_init_*</c></seecref> functions,
      which stores information, such as the hostname, and node name
      for later use:</p>

    <code type="none"><![CDATA[
int identification_number = 99;
int creation=1;
char *cookie="a secret cookie string"; /* An example */
const char* node_name = "einode@durin";
const char *cookie = NULL;
short creation = time(NULL) + 1;
ei_cnode ec;
ei_connect_init(ec,
                node_name,
                cookie,
                creation);    ]]></code>

    <p>For more information, see the
      <seecref marker="ei_connect"><c>ei_connect</c></seecref> module.</p>

    <p>After initialization, you set up the connection to the Erlang node.
      To specify the Erlang node you want to connect to, use the
      <c>ei_connect_*()</c> family of functions. The following example sets up the
      connection and is to result in a valid socket file descriptor:</p>

    <code type="none"><![CDATA[
int sockfd;
const char* node_name = "einode@durin"; /* An example */
if ((sockfd = ei_connect(ec, nodename)) < 0)
  fprintf(stderr, "ERROR: ei_connect failed");    ]]></code>

  </section>

  <section>
    <title>Using EPMD</title>
    <p><seecom marker="erts:epmd"><c>erts:epmd</c></seecom>
      is the Erlang Port Mapper Daemon. Distributed
      Erlang nodes register with <c>epmd</c> on the local host to
      indicate to other nodes that they exist and can accept connections.
      <c>epmd</c> maintains a register of
      node and port number information, and when a node wishes to connect to
      another node, it first contacts <c>epmd</c> to find the
      correct port number to connect to.</p>

    <p>When you use
      <seecref marker="ei_connect"><c>ei_connect</c></seecref>
      to connect to an Erlang node, a connection is first made to
      <c>epmd</c> and, if the node is known, a
      connection is then made to the Erlang node.</p>

    <p>C nodes can also register themselves with <c>epmd</c>
      if they want other
      nodes in the system to be able to find and connect to them.</p>

    <p>Before registering with <c>epmd</c>, you must first
      create a listen socket and bind it to a port. Then:</p>

    <code type="none"><![CDATA[
int pub;

pub = ei_publish(ec, port);    ]]></code>

    <p><c>pub</c> is a file descriptor now connected to
      <c>epmd</c>. <c>epmd</c>
      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 <c>epmd</c>.</p>

    <p>Notice that on some systems (such as VxWorks), 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, <c>epmd</c>
      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</p>

  </section>

  <section>
    <title>Sending and Receiving Erlang Messages</title>
    <p>Use one of the following two functions to send messages:</p>

    <list type="bulleted">
      <item><seecref marker="ei_connect#ei_send">
        <c>ei_send</c></seecref></item>
      <item><seecref marker="ei_connect#ei_reg_send">
        <c>ei_reg_send</c></seecref></item>
    </list>

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

    <p>Use one of the following two functions to receive messages:</p>

    <list type="bulleted">
      <item><seecref marker="ei_connect#ei_receive">
        <c>ei_receive</c></seecref></item>
      <item><seecref marker="ei_connect#ei_receive_msg">
        <c>ei_receive_msg</c></seecref></item>
    </list>

    <section>
      <title>Example of Sending Messages</title>
      <p>In the following example, <c>{Pid, hello_world}</c> is
        sent to a registered process <c>my_server</c>:</p>

      <code type="none"><![CDATA[
ei_x_buff buf;
ei_x_new_with_version(&buf);

ei_x_encode_tuple_header(&buf, 2);
ei_x_encode_pid(&buf, ei_self(ec));
ei_x_encode_atom(&buf, "Hello world");

ei_reg_send(ec,fd,"my_server",buf,buf.index);]]></code>

      <p>The first element of the tuple that is sent is your own
        pid. This enables <c>my_server</c> to reply.
        For more information about the primitives, see the
        <seecref marker="ei_connect"><c>ei_connect</c></seecref> module.</p>
    </section>

    <section>
      <title>Example of Receiving Messages</title>
      <p>In this example, <c>{Pid, Something}</c> is received.</p>

        <code type="none"><![CDATA[
erlang_msg msg;
int index = 0;
int version;
int arity = 0;
erlang_pid pid;
ei_x_buff buf;
ei_x_new(&buf);
for (;;) {
  int got = ei_xreceive_msg(fd, &msg, &x);
  if (got == ERL_TICK)
    continue;
  if (got == ERL_ERROR) {
    fprintf(stderr, "ei_xreceive_msg, got==%d", got);
    exit(1);
  }
  break;
}
ei_decode_version(buf.buff, &index, &version);
ei_decode_tuple_header(buf.buff, &index, &arity);
if (arity != 2) {
  fprintf(stderr, "got wrong message");
  exit(1);
}
ei_decode_pid(buf.buff, &index, &pid);     ]]></code>

      <p>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
        <c>ERL_TICK</c> message. This is done automatically by
        <c>ei_xreceive_msg()</c>. However, when this has occurred,
        <c>ei_xreceive_msg</c> returns <c>ERL_TICK</c> to
        the caller without storing a message into the
        <c>erlang_msg</c> structure.</p>

      <p>When a message has been received, it is the caller's responsibility
        to free the received message.</p>

      <p>For more information, see the
        <seecref marker="ei_connect"><c>ei_connect</c></seecref> and
        <seecref marker="ei"><c>ei</c></seecref> modules.</p>
    </section>
  </section>

  <section>
    <title>Remote Procedure Calls</title>
    <p>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.</p>

    <p>The following example checks if a specific Erlang process is alive:</p>

    <code type="none"><![CDATA[
int index = 0, is_alive;
ei_x_buff args, result;

ei_x_new(&result);
ei_x_new(&args);
ei_x_encode_list_header(&args, 1);
ei_x_encode_pid(&args, &check_pid);
ei_x_encode_empty_list(&args);

if (ei_rpc(&ec, fd, "erlang", "is_process_alive",
           args.buff, args.index, &result) < 0)
    handle_error();

if (ei_decode_version(result.buff, &index) < 0
    || ei_decode_bool(result.buff, &index, &is_alive) < 0)
    handle_error();    ]]></code>

    <p>For more information about <c>ei_rpc()</c> and its
      companions <c>ei_rpc_to()</c> and
      <c>ei_rpc_from()</c>, see the
      <seecref marker="ei_connect"><c>ei_connect</c></seecref> module.</p>
  </section>

  <section>
    <title>Using Global Names</title>
    <p>A C node has access to names registered through the
      <seeerl marker="kernel:global"><c>global</c></seeerl>
      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.</p>

    <p><c>Erl_Interface</c> 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.</p>

    <p>To see what names there are:</p>

    <code type="none"><![CDATA[
char **names;
int count;
int i;

names = ei_global_names(ec,fd,&count);

if (names) 
  for (i=0; i<count; i++) 
    printf("%s\n",names[i]);

free(names);    ]]></code>

    <p><seecref marker="ei_global#ei_global_names">
      <c>ei_global_names</c></seecref>
      allocates and returns a buffer containing
      all the names known to the <c>global</c> module in <c>Kernel</c>.
      <c>count</c> is initialized to
      indicate the number of names in the array. The array of strings in names
      is terminated by a <c>NULL</c> pointer, so it is not necessary to use
      <c>count</c> to determine when the last name is reached.</p>

    <p>It is the caller's responsibility to free the array.
      <c>ei_global_names</c> allocates the array and all the strings
      using a single call to <c>malloc()</c>, so
      <c>free(names)</c> is all that is necessary.</p>

    <p>To look up one of the names:</p>

    <code type="none"><![CDATA[
ETERM *pid;
char node[256];
erlang_pid the_pid;

if (ei_global_whereis(ec,fd,"schedule",&the_pid,node) < 0)
   fprintf(stderr, "ei_global_whereis error\n");    ]]></code>

    <p>If <c>"schedule"</c> is known to the
      <c>global</c> module in <c>Kernel</c>, an Erlang pid is
      written to the_pid. This pid that can be used to send messages to the schedule service.
      Also, <c>node</c> 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
      <seecref marker="ei_connect"><c>ei_connect</c></seecref>.</p>

    <p>Before registering a name, you should already have registered your
      port number with <c>epmd</c>. 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.</p>

    <p>Create a name that Erlang processes can use to communicate with your
      service:</p>

    <code type="none"><![CDATA[
ei_global_register(fd,servicename,ei_self(ec));    ]]></code>

    <p>After registering the name, use
        <seecref marker="ei_connect#ei_accept">
        <c>ei_accept</c></seecref>
        to wait for incoming connections.</p>

    <note>
      <p>Remember to free <c>pid</c> later with
        <seecref marker="ei#ei_x_free">
        <c>ei_x_free</c></seecref>.</p>
    </note>

    <p>To unregister a name:</p>

    <code type="none"><![CDATA[
ei_global_unregister(ec,fd,servicename);    ]]></code>
  </section>

  <section>
    <title>Using the Registry</title>

    <note><p>This functionality is deprecated as of OTP 23, and will be
    removed in OTP 24. Reasonably new <c>gcc</c> compilers will issue
    deprecation warnings. In order to disable these warnings, define the
    macro <c>EI_NO_DEPR_WARN</c>.</p></note>

    <p>This section describes the use of the registry, a simple mechanism
      for storing key-value pairs in a C-node, as well as backing them up or
      restoring them from an <c>Mnesia</c> table on an Erlang node. For more
      detailed information about the individual API functions, see the
      <seecref marker="registry"><c>registry</c></seecref> module.</p>

   <p>Keys are strings, that is, <c>NULL</c>-terminated arrays of characters, and
      values are arbitrary objects. Although integers and floating point numbers
      are treated specially by the registry, you can store strings or binary
      objects of any type as pointers.</p>

    <p>To start, open a registry:</p>

    <code type="none"><![CDATA[
ei_reg *reg;

reg = ei_reg_open(45);    ]]></code>

    <p>The number <c>45</c> in the example indicates the approximate number of
      objects that you expect to store in the registry. Internally the
      registry uses hash tables with collision chaining, so there is no
      absolute upper limit on the number of objects that the registry can
      contain, but if performance or memory usage is important, then you
      are to choose a number accordingly. The registry can be resized later.</p>

    <p>You can open as many registries as you like (if memory permits).</p>

    <p>Objects are stored and retrieved through set and get functions.
      The following example shows how to store integers, floats, strings,
      and arbitrary binary objects:</p>

    <code type="none"><![CDATA[
struct bonk *b = malloc(sizeof(*b));
char *name = malloc(7);

ei_reg_setival(reg,"age",29); 
ei_reg_setfval(reg,"height",1.85);

strcpy(name,"Martin");
ei_reg_setsval(reg,"name",name); 

b->l = 42;
b->m = 12;
ei_reg_setpval(reg,"jox",b,sizeof(*b));    ]]></code>

    <p>If you try to store an object in the registry and there is an
      existing object with the same key, the new value replaces the old
      one. This is done regardless of whether the new object and the old one
      have the same type, so you can, for example, replace a string with an
      integer. If the existing value is a string or binary, it is freed
      before the new value is assigned.</p>

    <p>Stored values are retrieved from the registry as follows:</p>

    <code type="none"><![CDATA[
long i;
double f;
char *s;
struct bonk *b;
int size;

i = ei_reg_getival(reg,"age");
f = ei_reg_getfval(reg,"height");
s = ei_reg_getsval(reg,"name");
b = ei_reg_getpval(reg,"jox",&size);    ]]></code>

    <p>In all the above examples, the object must exist and it must be of
      the right type for the specified operation. If you do not know the
      type of an object, you can ask:</p>

    <code type="none"><![CDATA[
struct ei_reg_stat buf;

ei_reg_stat(reg,"name",&buf);    ]]></code>

    <p>Buf is initialized to contain object attributes.</p>

    <p>Objects can be removed from the registry:</p>

    <code type="none"><![CDATA[
ei_reg_delete(reg,"name");    ]]></code>

    <p>When you are finished with a registry, close it to remove all the
      objects and free the memory back to the system:</p>

    <code type="none"><![CDATA[
ei_reg_close(reg);    ]]></code>

    <section>
      <title>Backing Up the Registry to Mnesia</title>
      <p>The contents of a registry can be backed up to
        <seeerl marker="mnesia:mnesia"><c>Mnesia</c></seeerl> on a "nearby" Erlang
        node. You must provide an open connection to the Erlang node
        (see <seecref marker="ei_connect"><c>ei_connect</c></seecref>).
        Also, <c>Mnesia</c> 3.0 or later must be running
        on the Erlang node before the backup is initiated:</p>

      <code type="none"><![CDATA[
ei_reg_dump(fd, reg, "mtab", dumpflags);      ]]></code>

      <p>This example back up the contents of the registry to the
        specified <c>Mnesia</c> table <c>"mtab"</c>.
        Once a registry has been backed
        up to <c>Mnesia</c> like this, more backups only affect
        objects that have been modified since the most recent backup, that is,
        objects that have been created, changed, or deleted. The backup
        operation is done as a single atomic transaction, so that either the
        entire backup is performed or none of it.</p>

      <p>Likewise, a registry can be restored from a <c>Mnesia</c> table:</p>

      <code type="none"><![CDATA[
ei_reg_restore(fd, reg, "mtab");      ]]></code>

      <p>This reads the entire contents of <c>"mtab"</c> into the
        specified registry. After the restore, all the objects in the registry
        are marked as unmodified, so a later backup only affects
        objects that you have modified since the restore.</p>

      <p>Notice that if you restore to a non-empty registry, objects in the
        table overwrite objects in the registry with the same keys. Also,
        the <em>entire</em> contents of the registry is marked as unmodified
        after the restore, including any modified objects that were not
        overwritten by the restore operation. This may not be your
        intention.</p>
    </section>

    <section>
      <title>Storing Strings and Binaries</title>
      <p>When string or binary objects are stored in the registry it is
        important that some simple guidelines are followed.</p>

      <p>Most importantly, the object must have been created with a single call
        to <c>malloc()</c> (or similar), so that it can later be
        removed by a single call to <c>free()</c>.
        Objects are freed by the registry
        when it is closed, or when you assign a new value to an object that
        previously contained a string or binary.</p>

      <p>Notice that if you store binary objects that are context-dependent
        (for example, containing pointers or open file descriptors),
        they lose their meaning if they are backed up to a <c>Mnesia</c> table
        and later restored in a different context.</p>

      <p>When you retrieve a stored string or binary value from the registry,
        the registry maintains a pointer to the object and you are passed a
        copy of that pointer. You should never free an object retrieved in
        this manner because when the registry later attempts to free it, a
        runtime error occurs that likely causes the C-node to crash.</p>

      <p>You are free to modify the contents of an object retrieved this way.
        However, when you do so, the registry is not aware of your changes,
        possibly causing it to be missed the next time you make an
        <c>Mnesia</c> backup of the registry contents. This can be avoided if
        you mark the object as dirty after any such changes with
        <seecref marker="registry#ei_reg_markdirty">
        <c>ei_reg_markdirty</c></seecref>, or pass appropriate flags to
        <seecref marker="registry#ei_reg_dump">
        <c>ei_reg_dump</c></seecref>.</p>
    </section>
  </section>
</chapter>
