The R13B03 release.OTP_R13B03

1 files changed, 148 insertions, 0 deletions

diff --git a/system/doc/efficiency_guide/drivers.xml b/system/doc/efficiency_guide/drivers.xml
new file mode 100644
index 0000000000..9fe54fb19a
--- /dev/null
+++ b/system/doc/efficiency_guide/drivers.xml
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2009</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Drivers</title>
+    <prepared>Bjorn Gustavsson</prepared>
+    <docno></docno>
+    <date>2009-11-16</date>
+    <rev></rev>
+    <file>drivers.xml</file>
+  </header>
+
+  <p>This chapter provides a (very) brief overview on how to write efficient
+  drivers. It is assumed that you already have a good understanding of
+  drivers.</p>
+
+  <section>
+    <title>Drivers and concurrency</title>
+
+    <p>The run-time system will always take a lock before running
+    any code in a driver.</p>
+
+    <p>By default, that lock will be at the driver level, meaning that
+    if several ports has been opened to the same driver, only code for
+    one port at the same time can be running.</p>
+
+    <p>A driver can be configured to instead have one lock for each port.</p>
+
+    <p>If a driver is used in a functional way (i.e. it holds no state,
+    but only does some heavy calculation and returns a result), several
+    ports with registered names can be opened beforehand and the port to
+    be used can be chosen based on the scheduler ID like this:</p>
+
+    <code type="none">
+-define(PORT_NAMES(),
+	{some_driver_01, some_driver_02, some_driver_03, some_driver_04,
+	 some_driver_05, some_driver_06, some_driver_07, some_driver_08,
+	 some_driver_09, some_driver_10, some_driver_11, some_driver_12,
+	 some_driver_13, some_driver_14, some_driver_15, some_driver_16}).
+
+client_port() ->
+    element(erlang:system_info(scheduler_id) rem tuple_size(?PORT_NAMES()) + 1,
+	    ?PORT_NAMES()).</code>
+
+    <p>As long as there are no more than 16 schedulers, there will never
+    be any lock contention on the port lock for the driver.</p>	    
+
+  </section>
+
+  <section>
+    <title>Avoiding copying of binaries when calling a driver</title>
+
+    <p>There are basically two ways to avoid copying a binary that is
+    sent to a driver.</p>
+
+    <p>If the <c>Data</c> argument for
+    <seealso marker="erts:erlang#port_control/3">port_control/3</seealso>
+    is a binary, the driver will be passed a pointer to the contents of
+    the binary and the binary will not be copied.
+    If the <c>Data</c> argument is an iolist (list of binaries and lists),
+    all binaries in the iolist will be copied.</p>
+
+    <p>Therefore, if you want to send both a pre-existing binary and some
+    additional data to a driver without copying the binary, you must call
+    <c>port_control/3</c> twice; once with the binary and once with the
+    additional data. However, that will only work if there is only one
+    process communicating with the port (because otherwise another process
+    could call the driver in-between the calls).</p>
+
+    <p>Another way to avoid copying binaries is to implement an <c>outputv</c>
+    callback (instead of an <c>output</c> callback) in the driver.
+    If a driver has an <c>outputv</c> callback, refc binaries passed
+    in an iolist in the <c>Data</c> argument for
+    <seealso marker="erts:erlang#port_command/2">port_command/2</seealso>
+    will be passed as references to the driver.</p>
+  </section>
+
+  <section>
+    <title>Returning small binaries from a driver</title>
+
+    <p>The run-time system can represent binaries up to 64 bytes as
+    heap binaries. They will always be copied when sent in a messages,
+    but they will require less memory if they are not sent to another
+    process and garbage collection is cheaper.</p>
+
+    <p>If you know that the binaries you return are always small,
+    you should use driver API calls that do not require a pre-allocated
+    binary, for instance
+    <seealso marker="erts:erl_driver#int driver_output-3">driver_output()</seealso>
+    or 
+    <seealso marker="erts:erl_driver#int driver_output_term-3">driver_output_term()</seealso>
+    using the <c>ERL_DRV_BUF2BINARY</c> format,
+    to allow the run-time to construct a heap binary.</p>
+
+  </section>
+
+  <section>
+    <title>Returning big binaries without copying from a driver</title>
+
+    <p>To avoid copying data when a big binary is sent or returned from
+    the driver to an Erlang process, the driver must first allocate the
+    binary and then send it to an Erlang process in some way.</p>
+    
+    <p>Use <seealso marker="erts:erl_driver#ErlDrvBinary* driver_alloc_binary-1">driver_alloc_binary()</seealso> to allocate a binary.</p>
+
+    <p>There are several ways to send a binary created with
+    <c>driver_alloc_binary()</c>.</p>
+
+    <list type="bulleted">
+    <item><p>From the <c>control</c> callback, a binary can be returned provided
+        that
+	<seealso marker="erts:erl_driver#void set_port_control_flags-2">set_port_control()</seealso>
+	 has been called with the flag value <c>PORT_CONTROL_FLAG_BINARY</c>.</p>
+    </item>
+
+    <item><p>A single binary can be sent with
+    <seealso marker="erts:erl_driver#int driver_output_binary-6">driver_output_binary()</seealso>.</p></item>
+
+    <item><p>Using
+    <seealso marker="erts:erl_driver#int driver_output_term-3">driver_output_term()</seealso>
+    or
+    <seealso marker="erts:erl_driver#int driver_send_term-4">driver_send_term()</seealso>,
+    a binary can be included in an Erlang term.</p>
+    </item>
+    </list>
+
+  </section>
+
+</chapter>