← Back to branch summary

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

« back to all changes in this revision

Viewing changes to system/doc/efficiency_guide/drivers.xml

  • 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/efficiency_guide/drivers.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2009</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>Drivers</title>
 
25
    <prepared>Bjorn Gustavsson</prepared>
 
26
    <docno></docno>
 
27
    <date>2009-11-16</date>
 
28
    <rev></rev>
 
29
    <file>drivers.xml</file>
 
30
  </header>
 
31
 
 
32
  <p>This chapter provides a (very) brief overview on how to write efficient
 
33
  drivers. It is assumed that you already have a good understanding of
 
34
  drivers.</p>
 
35
 
 
36
  <section>
 
37
    <title>Drivers and concurrency</title>
 
38
 
 
39
    <p>The run-time system will always take a lock before running
 
40
    any code in a driver.</p>
 
41
 
 
42
    <p>By default, that lock will be at the driver level, meaning that
 
43
    if several ports has been opened to the same driver, only code for
 
44
    one port at the same time can be running.</p>
 
45
 
 
46
    <p>A driver can be configured to instead have one lock for each port.</p>
 
47
 
 
48
    <p>If a driver is used in a functional way (i.e. it holds no state,
 
49
    but only does some heavy calculation and returns a result), several
 
50
    ports with registered names can be opened beforehand and the port to
 
51
    be used can be chosen based on the scheduler ID like this:</p>
 
52
 
 
53
    <code type="none">
 
54
-define(PORT_NAMES(),
 
55
        {some_driver_01, some_driver_02, some_driver_03, some_driver_04,
 
56
         some_driver_05, some_driver_06, some_driver_07, some_driver_08,
 
57
         some_driver_09, some_driver_10, some_driver_11, some_driver_12,
 
58
         some_driver_13, some_driver_14, some_driver_15, some_driver_16}).
 
59
 
 
60
client_port() ->
 
61
    element(erlang:system_info(scheduler_id) rem tuple_size(?PORT_NAMES()) + 1,
 
62
            ?PORT_NAMES()).</code>
 
63
 
 
64
    <p>As long as there are no more than 16 schedulers, there will never
 
65
    be any lock contention on the port lock for the driver.</p>     
 
66
 
 
67
  </section>
 
68
 
 
69
  <section>
 
70
    <title>Avoiding copying of binaries when calling a driver</title>
 
71
 
 
72
    <p>There are basically two ways to avoid copying a binary that is
 
73
    sent to a driver.</p>
 
74
 
 
75
    <p>If the <c>Data</c> argument for
 
76
    <seealso marker="erts:erlang#port_control/3">port_control/3</seealso>
 
77
    is a binary, the driver will be passed a pointer to the contents of
 
78
    the binary and the binary will not be copied.
 
79
    If the <c>Data</c> argument is an iolist (list of binaries and lists),
 
80
    all binaries in the iolist will be copied.</p>
 
81
 
 
82
    <p>Therefore, if you want to send both a pre-existing binary and some
 
83
    additional data to a driver without copying the binary, you must call
 
84
    <c>port_control/3</c> twice; once with the binary and once with the
 
85
    additional data. However, that will only work if there is only one
 
86
    process communicating with the port (because otherwise another process
 
87
    could call the driver in-between the calls).</p>
 
88
 
 
89
    <p>Another way to avoid copying binaries is to implement an <c>outputv</c>
 
90
    callback (instead of an <c>output</c> callback) in the driver.
 
91
    If a driver has an <c>outputv</c> callback, refc binaries passed
 
92
    in an iolist in the <c>Data</c> argument for
 
93
    <seealso marker="erts:erlang#port_command/2">port_command/2</seealso>
 
94
    will be passed as references to the driver.</p>
 
95
  </section>
 
96
 
 
97
  <section>
 
98
    <title>Returning small binaries from a driver</title>
 
99
 
 
100
    <p>The run-time system can represent binaries up to 64 bytes as
 
101
    heap binaries. They will always be copied when sent in a messages,
 
102
    but they will require less memory if they are not sent to another
 
103
    process and garbage collection is cheaper.</p>
 
104
 
 
105
    <p>If you know that the binaries you return are always small,
 
106
    you should use driver API calls that do not require a pre-allocated
 
107
    binary, for instance
 
108
    <seealso marker="erts:erl_driver#int driver_output-3">driver_output()</seealso>
 
109
    or 
 
110
    <seealso marker="erts:erl_driver#int driver_output_term-3">driver_output_term()</seealso>
 
111
    using the <c>ERL_DRV_BUF2BINARY</c> format,
 
112
    to allow the run-time to construct a heap binary.</p>
 
113
 
 
114
  </section>
 
115
 
 
116
  <section>
 
117
    <title>Returning big binaries without copying from a driver</title>
 
118
 
 
119
    <p>To avoid copying data when a big binary is sent or returned from
 
120
    the driver to an Erlang process, the driver must first allocate the
 
121
    binary and then send it to an Erlang process in some way.</p>
 
122
    
 
123
    <p>Use <seealso marker="erts:erl_driver#ErlDrvBinary* driver_alloc_binary-1">driver_alloc_binary()</seealso> to allocate a binary.</p>
 
124
 
 
125
    <p>There are several ways to send a binary created with
 
126
    <c>driver_alloc_binary()</c>.</p>
 
127
 
 
128
    <list type="bulleted">
 
129
    <item><p>From the <c>control</c> callback, a binary can be returned provided
 
130
        that
 
131
        <seealso marker="erts:erl_driver#void set_port_control_flags-2">set_port_control()</seealso>
 
132
         has been called with the flag value <c>PORT_CONTROL_FLAG_BINARY</c>.</p>
 
133
    </item>
 
134
 
 
135
    <item><p>A single binary can be sent with
 
136
    <seealso marker="erts:erl_driver#int driver_output_binary-6">driver_output_binary()</seealso>.</p></item>
 
137
 
 
138
    <item><p>Using
 
139
    <seealso marker="erts:erl_driver#int driver_output_term-3">driver_output_term()</seealso>
 
140
    or
 
141
    <seealso marker="erts:erl_driver#int driver_send_term-4">driver_send_term()</seealso>,
 
142
    a binary can be included in an Erlang term.</p>
 
143
    </item>
 
144
    </list>
 
145
 
 
146
  </section>
 
147
 
 
148
</chapter>