← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to system/doc/tutorial/erl_interface.xmlsrc

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/tutorial/erl_interface.xmlsrc
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2000</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Erl_Interface</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>erl_interface.xml</file>
 
30
  </header>
 
31
  <p>This is an example of how to solve the <seealso marker="example">example problem</seealso> by using a port and <c>erl_interface</c>. It is necessary to read the <seealso marker="c_port">port example</seealso> before reading this chapter.</p>
 
32
 
 
33
  <section>
 
34
    <title>Erlang Program</title>
 
35
    <p>The example below shows an Erlang program communicating with a C program over a plain port with home made encoding.</p>
 
36
    <codeinclude file="complex1.erl" type="erl"/>
 
37
    <p>Compared to the Erlang module 
 
38
      above used for the plain port, there are two differences when using Erl_Interface on the C side: Since Erl_Interface operates on the Erlang external term format the port must be set to use binaries and, instead of inventing an encoding/decoding scheme, the BIFs <c>term_to_binary/1</c> and <c>binary_to_term/1</c> should be used. That is:</p>
 
39
    <pre>
 
40
open_port({spawn, ExtPrg}, [{packet, 2}])</pre>
 
41
    <p>is replaced with:</p>
 
42
    <pre>
 
43
open_port({spawn, ExtPrg}, [{packet, 2}, binary])</pre>
 
44
    <p>And:</p>
 
45
    <pre>
 
46
Port ! {self(), {command, encode(Msg)}},
 
47
receive
 
48
  {Port, {data, Data}} ->
 
49
    Caller ! {complex, decode(Data)}
 
50
end</pre>
 
51
    <p>is replaced with:</p>
 
52
    <pre>
 
53
Port ! {self(), {command, term_to_binary(Msg)}},
 
54
receive
 
55
  {Port, {data, Data}} ->
 
56
    Caller ! {complex, binary_to_term(Data)}
 
57
end</pre>
 
58
    <p>The resulting Erlang program is shown below.</p>
 
59
    <codeinclude file="complex2.erl" type="erl"/>
 
60
    <p>Note that calling <c>complex2:foo/1</c> and <c>complex2:bar/1</c> will result in the tuple <c>{foo,X}</c> or <c>{bar,Y}</c> being sent to the <c>complex</c> process, which will code them as binaries and send them to the port. This means that the C program must be able to handle these two tuples.</p>
 
61
  </section>
 
62
 
 
63
  <section>
 
64
    <title>C Program</title>
 
65
    <p>The example below shows a C program communicating with an Erlang program over a plain port with home made encoding.</p>
 
66
    <codeinclude file="port.c" type="c"/>
 
67
    <p>Compared to the C program above
 
68
      used for the plain port the <c>while</c>-loop must be rewritten. Messages coming from the port will be on the Erlang external term format. They should be converted into an <c>ETERM</c> struct, a C struct similar to an Erlang term. The result of calling <c>foo()</c> or <c>bar()</c> must be converted to the Erlang external term format before being sent back to the port. But before calling any other <c>erl_interface</c> function, the memory handling must be initiated.</p>
 
69
    <pre>
 
70
erl_init(NULL, 0);</pre>
 
71
    <p>For reading from and writing to the port the functions <c>read_cmd()</c> and <c>write_cmd()</c> from the erl_comm.c example below 
 
72
      can still be used.
 
73
    </p>
 
74
    <codeinclude file="erl_comm.c" type="c"/>
 
75
    <p>The function <c>erl_decode()</c> from <c>erl_marshal</c> will convert the binary into an <c>ETERM</c> struct.</p>
 
76
    <pre>
 
77
int main() {
 
78
  ETERM *tuplep;
 
79
 
 
80
  while (read_cmd(buf) > 0) {
 
81
    tuplep = erl_decode(buf);</pre>
 
82
    <p>In this case <c>tuplep</c> now points to an <c>ETERM</c> struct representing a tuple with two elements; the function name (atom) and the argument (integer). By using the function <c>erl_element()</c> from <c>erl_eterm</c> it is possible to extract these elements, which also must be declared as pointers to an <c>ETERM</c> struct.</p>
 
83
    <pre>
 
84
    fnp = erl_element(1, tuplep);
 
85
    argp = erl_element(2, tuplep);</pre>
 
86
    <p>The macros <c>ERL_ATOM_PTR</c> and <c>ERL_INT_VALUE</c> from <c>erl_eterm</c> can be used to obtain the actual values of the atom and the integer. The atom value is represented as a string. By comparing this value with the strings "foo" and "bar" it can be decided which function to call.</p>
 
87
    <pre>
 
88
    if (strncmp(ERL_ATOM_PTR(fnp), "foo", 3) == 0) {
 
89
      res = foo(ERL_INT_VALUE(argp));
 
90
    } else if (strncmp(ERL_ATOM_PTR(fnp), "bar", 3) == 0) {
 
91
      res = bar(ERL_INT_VALUE(argp));
 
92
    }</pre>
 
93
    <p>Now an <c>ETERM</c> struct representing the integer result can be constructed using the function <c>erl_mk_int()</c> from <c>erl_eterm</c>. It is also possible to use the function <c>erl_format()</c> from the module <c>erl_format</c>.</p>
 
94
    <pre>
 
95
    intp = erl_mk_int(res);</pre>
 
96
    <p>The resulting <c>ETERM</c> struct is converted into the Erlang external term format using the function <c>erl_encode()</c> from <c>erl_marshal</c> and sent to Erlang using <c>write_cmd()</c>.</p>
 
97
    <pre>
 
98
    erl_encode(intp, buf);
 
99
    write_cmd(buf, erl_eterm_len(intp));</pre>
 
100
    <p>Last, the memory allocated by the <c>ETERM</c> creating functions must be freed.</p>
 
101
    <pre>
 
102
    erl_free_compound(tuplep);
 
103
    erl_free_term(fnp);
 
104
    erl_free_term(argp);
 
105
    erl_free_term(intp);</pre>
 
106
    <p>The resulting C program is shown below:</p>
 
107
    <codeinclude file="ei.c" type="c"/>
 
108
  </section>
 
109
 
 
110
  <section>
 
111
    <title>Running the Example</title>
 
112
    <p>1. Compile the C code, providing the paths to the include files <c>erl_interface.h</c> and <c>ei.h</c>, and to the libraries <c>erl_interface</c> and <c>ei</c>.</p>
 
113
    <pre>
 
114
unix> <input>gcc -o extprg -I/usr/local/otp/lib/erl_interface-3.2.1/include \\ </input>
 
115
<input>      -L/usr/local/otp/lib/erl_interface-3.2.1/lib \\ </input>
 
116
<input>      complex.c erl_comm.c ei.c -lerl_interface -lei</input></pre>
 
117
    <p>In R5B and later versions of OTP, the <c>include</c> and <c>lib</c> directories are situated under <c>OTPROOT/lib/erl_interface-VSN</c>, where <c>OTPROOT</c> is the root directory of the OTP installation (<c>/usr/local/otp</c> in the example above) and <c>VSN</c> is the version of the <c>erl_interface</c> application (3.2.1 in the example above).      <br></br>
 
118
 
 
119
      In R4B and earlier versions of OTP, <c>include</c> and <c>lib</c> are situated under <c>OTPROOT/usr</c>.</p>
 
120
    <p>2. Start Erlang and compile the Erlang code.</p>
 
121
    <pre>
 
122
unix> <input>erl</input>
 
123
Erlang (BEAM) emulator version 4.9.1.2
 
124
 
 
125
Eshell V4.9.1.2 (abort with ^G)
 
126
1> <input>c(complex2).</input>
 
127
{ok,complex2}</pre>
 
128
    <p>3. Run the example.</p>
 
129
    <pre>
 
130
2> <input>complex2:start("extprg").</input>
 
131
&lt;0.34.0>
 
132
3> <input>complex2:foo(3).</input>
 
133
4
 
134
4> <input>complex2:bar(5).</input>
 
135
10
 
136
5> <input>complex2:bar(352).</input>
 
137
704
 
138
6> <input>complex2:stop().</input>
 
139
stop</pre>
 
140
  </section>
 
141
</chapter>
 
142