# 5 Erl_Interface

This section outlines an example of how to solve the example problem in Problem Example by using a port and Erl_Interface. It is necessary to read the port example in Ports before reading this section.

###
5.1 Erlang Program

The following example shows an Erlang program communicating with a C program over a plain port with home made encoding:

    -module(complex1).
    -export([start/1, stop/0, init/1]).
    -export([foo/1, bar/1]).

    start(ExtPrg) ->
        spawn(?MODULE, init, [ExtPrg]).
    stop() ->
        complex ! stop.

    foo(X) ->
        call_port({foo, X}).
    bar(Y) ->
        call_port({bar, Y}).

    call_port(Msg) ->
        complex ! {call, self(), Msg},
        receive
    	{complex, Result} ->
    	    Result
        end.

    init(ExtPrg) ->
        register(complex, self()),
        process_flag(trap_exit, true),
        Port = open_port({spawn, ExtPrg}, [{packet, 2}]),
        loop(Port).

    loop(Port) ->
        receive
    	{call, Caller, Msg} ->
    	    Port ! {self(), {command, encode(Msg)}},
    	    receive
    		{Port, {data, Data}} ->
    		    Caller ! {complex, decode(Data)}
    	    end,
    	    loop(Port);
    	stop ->
    	    Port ! {self(), close},
    	    receive
    		{Port, closed} ->
    		    exit(normal)
    	    end;
    	{'EXIT', Port, Reason} ->
    	    exit(port_terminated)
        end.

    encode({foo, X}) -> [1, X];
    encode({bar, Y}) -> [2, Y].

    decode([Int]) -> Int.

There are two differences when using Erl_Interface on the C side compared to the example in Ports, using only the plain port:

- As Erl_Interface operates on the Erlang external term format, the port must be set to use binaries.
- Instead of inventing an encoding/decoding scheme, the term_to_binary/1 and binary_to_term/1 BIFs are to be used.

That is:

    open_port({spawn, ExtPrg}, [{packet, 2}])

is replaced with:

    open_port({spawn, ExtPrg}, [{packet, 2}, binary])

And:

    Port ! {self(), {command, encode(Msg)}},
    receive
      {Port, {data, Data}} ->
        Caller ! {complex, decode(Data)}
    end

is replaced with:

    Port ! {self(), {command, term_to_binary(Msg)}},
    receive
      {Port, {data, Data}} ->
        Caller ! {complex, binary_to_term(Data)}
    end

The resulting Erlang program is as follows:

    -module(complex2).
    -export([start/1, stop/0, init/1]).
    -export([foo/1, bar/1]).

    start(ExtPrg) ->
        spawn(?MODULE, init, [ExtPrg]).
    stop() ->
        complex ! stop.

    foo(X) ->
        call_port({foo, X}).
    bar(Y) ->
        call_port({bar, Y}).

    call_port(Msg) ->
        complex ! {call, self(), Msg},
        receive
    	{complex, Result} ->
    	    Result
        end.

    init(ExtPrg) ->
        register(complex, self()),
        process_flag(trap_exit, true),
        Port = open_port({spawn, ExtPrg}, [{packet, 2}, binary]),
        loop(Port).

    loop(Port) ->
        receive
    	{call, Caller, Msg} ->
    	    Port ! {self(), {command, term_to_binary(Msg)}},
    	    receive
    		{Port, {data, Data}} ->
    		    Caller ! {complex, binary_to_term(Data)}
    	    end,
    	    loop(Port);
    	stop ->
    	    Port ! {self(), close},
    	    receive
    		{Port, closed} ->
    		    exit(normal)
    	    end;
    	{'EXIT', Port, Reason} ->
    	    exit(port_terminated)
        end.

Notice that calling complex2:foo/1 and complex2:bar/1 results in the tuple {foo,X} or {bar,Y} being sent to the complex process, which codes them as binaries and sends them to the port. This means that the C program must be able to handle these two tuples.

###
5.2 C Program

The following example shows a C program communicating with an Erlang program over a plain port with the Erlang external term format encoding:

    /* ei.c */

    #include "ei.h"
    #include <unistd.h>
    #include <string.h>
    #include <stdlib.h>

    typedef unsigned char byte;

    int read_cmd(byte *buf);
    int write_cmd(byte *buf, int len);
    int foo(int x);
    int bar(int y);

    static void fail(int place) {
        fprintf(stderr, "Something went wrong %d\n", place);
        exit(1);
    }

    int main() {
        byte buf[100];
        int index = 0;
        int version = 0;
        int arity = 0;
        char atom[128];
        long in = 0;
        int res = 0;
        ei_x_buff res_buf;
        ei_init();
        while (read_cmd(buf) > 0) {
            if (ei_decode_version(buf, &index, &version) != 0)
                fail(1);
            if (ei_decode_tuple_header(buf, &index, &arity) != 0)
                fail(2);
            if (arity != 2)
                fail(3);
            if (ei_decode_atom(buf, &index, atom) != 0)
                fail(4);
            if (ei_decode_long(buf, &index, &in) != 0)
                fail(5);
            if (strncmp(atom, "foo", 3) == 0) {
                res = foo((int)in);
            } else if (strncmp(atom, "bar", 3) == 0) {
                res = bar((int)in);
            }
            if (ei_x_new_with_version(&res_buf) != 0)
                fail(6);
            if (ei_x_encode_long(&res_buf, res) != 0)
                fail(7);
            write_cmd(res_buf.buff, res_buf.index);

            if (ei_x_free(&res_buf) != 0)
                fail(8);
            index = 0;
        }
    }

The following functions, read_cmd() and write_cmd(), from the erl_comm.c example in Ports can still be used for reading from and writing to the port:

    /* erl_comm.c */

    #include <stdio.h>
    #include <unistd.h>

    typedef unsigned char byte;

    int read_exact(byte *buf, int len)
    {
      int i, got=0;

      do {
          if ((i = read(0, buf+got, len-got)) <= 0){
              return(i);
          }
        got += i;
      } while (got<len);

      return(len);
    }

    int write_exact(byte *buf, int len)
    {
      int i, wrote = 0;

      do {
        if ((i = write(1, buf+wrote, len-wrote)) <= 0)
          return (i);
        wrote += i;
      } while (wrote<len);

      return (len);
    }

    int read_cmd(byte *buf)
    {
      int len;

      if (read_exact(buf, 2) != 2)
        return(-1);
      len = (buf[0] << 8) | buf[1];
      return read_exact(buf, len);
    }

    int write_cmd(byte *buf, int len)
    {
      byte li;

      li = (len >> 8) & 0xff;
      write_exact(&li, 1);

      li = len & 0xff;
      write_exact(&li, 1);

      return write_exact(buf, len);
    }

###
5.3 Running the Example

Step 1. Compile the C code. This provides the paths to the include file ei.h, and also to the library ei:

    unix> gcc -o extprg -I/usr/local/otp/lib/erl_interface-3.9.2/include \
          -L/usr/local/otp/lib/erl_interface-3.9.2/lib \
          complex.c erl_comm.c ei.c -lei -lpthread

In Erlang/OTP R5B and later versions of OTP, the include and lib directories are situated under OTPROOT/lib/erl_interface-VSN, where OTPROOT is the root directory of the OTP installation (/usr/local/otp in the recent example) and VSN is the version of the Erl_interface application (3.2.1 in the recent example).

In R4B and earlier versions of OTP, include and lib are situated under OTPROOT/usr.

Step 2. Start Erlang and compile the Erlang code:

    unix> erl
    Erlang (BEAM) emulator version 4.9.1.2

    Eshell V4.9.1.2 (abort with ^G)
    1> c(complex2).
    {ok,complex2}

Step 3. Run the example:

    2> complex2:start("./extprg").
    <0.34.0>
    3> complex2:foo(3).
    4
    4> complex2:bar(5).
    10
    5> complex2:bar(352).
    704
    6> complex2:stop().
    stop