<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:erl="http://erlang.org" xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../otp_doc.css" type="text/css">
<title>Erlang -- Drivers</title>
</head>
<body>
<div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<div class="erlang-logo-wrapper"><a href="../index.html"><img alt="Erlang Logo" src="../erlang-logo.png" class="erlang-logo"></a></div>
<p class="section-title">Efficiency Guide</p>
<p class="section-subtitle">User's Guide</p>
<p class="section-version">Version 10.2.3</p>
<ul class="panel-sections">
<li><a href="users_guide.html">User's Guide</a></li>
<li><a href="../pdf/otp-system-documentation-10.2.3.pdf">PDF</a></li>
<li><a href="../index.html">Top</a></li>
</ul>
<ul class="expand-collapse-items">
<li><a href="javascript:openAllFlips()">Expand All</a></li>
<li><a href="javascript:closeAllFlips()">Contract All</a></li>
</ul>
<h3>Chapters</h3>
<ul class="flipMenu" imagepath="../js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="introduction.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="introduction.html#purpose">Purpose</a></li>
<li title="Prerequisites"><a href="introduction.html#prerequisites">Prerequisites</a></li>
</ul>
</li>
<li id="no" title="The Seven Myths of Erlang Performance" expanded="false">The Seven Myths of Erlang Performance<ul>
<li><a href="myths.html">
Top of chapter
</a></li>
<li title="Myth: Tail-Recursive Functions are Much Faster
Than Recursive Functions"><a href="myths.html#myth--tail-recursive-functions-are-much-faster-----than-recursive-functions">Myth: Tail-Recursive Functions are Much Faster
Than Recursive Functions</a></li>
<li title='Myth: Operator "++" is Always Bad'><a href="myths.html#myth--operator--++--is-always-bad">Myth: Operator "++" is Always Bad</a></li>
<li title="Myth: Strings are Slow"><a href="myths.html#myth--strings-are-slow">Myth: Strings are Slow</a></li>
<li title="Myth: Repairing a Dets File is Very Slow"><a href="myths.html#myth--repairing-a-dets-file-is-very-slow">Myth: Repairing a Dets File is Very Slow</a></li>
<li title="Myth: BEAM is a Stack-Based Byte-Code Virtual Machine
(and Therefore Slow)"><a href="myths.html#myth--beam-is-a-stack-based-byte-code-virtual-machine------and-therefore-slow-">Myth: BEAM is a Stack-Based Byte-Code Virtual Machine
(and Therefore Slow)</a></li>
<li title='Myth: Use "_" to Speed Up Your Program When a Variable
is Not Used'><a href="myths.html#myth--use--_--to-speed-up-your-program-when-a-variable-----is-not-used">Myth: Use "_" to Speed Up Your Program When a Variable
is Not Used</a></li>
<li title="Myth: A NIF Always Speeds Up Your Program"><a href="myths.html#myth--a-nif-always-speeds-up-your-program">Myth: A NIF Always Speeds Up Your Program</a></li>
</ul>
</li>
<li id="no" title="Common Caveats" expanded="false">Common Caveats<ul>
<li><a href="commoncaveats.html">
Top of chapter
</a></li>
<li title="Timer Module"><a href="commoncaveats.html#timer-module">Timer Module</a></li>
<li title="list_to_atom/1"><a href="commoncaveats.html#list_to_atom-1">list_to_atom/1</a></li>
<li title="length/1"><a href="commoncaveats.html#length-1">length/1</a></li>
<li title="setelement/3"><a href="commoncaveats.html#setelement-3">setelement/3</a></li>
<li title="size/1"><a href="commoncaveats.html#size-1">size/1</a></li>
<li title="split_binary/2"><a href="commoncaveats.html#split_binary-2">split_binary/2</a></li>
</ul>
</li>
<li id="no" title="Constructing and Matching Binaries" expanded="false">Constructing and Matching Binaries<ul>
<li><a href="binaryhandling.html">
Top of chapter
</a></li>
<li title="How Binaries are Implemented"><a href="binaryhandling.html#how-binaries-are-implemented">How Binaries are Implemented</a></li>
<li title="Constructing Binaries"><a href="binaryhandling.html#constructing-binaries">Constructing Binaries</a></li>
<li title="Matching Binaries"><a href="binaryhandling.html#matching-binaries">Matching Binaries</a></li>
<li title="Historical Note"><a href="binaryhandling.html#historical-note">Historical Note</a></li>
</ul>
</li>
<li id="no" title="List Handling" expanded="false">List Handling<ul>
<li><a href="listHandling.html">
Top of chapter
</a></li>
<li title="Creating a List"><a href="listHandling.html#creating-a-list">Creating a List</a></li>
<li title="List Comprehensions"><a href="listHandling.html#list-comprehensions">List Comprehensions</a></li>
<li title="Deep and Flat Lists"><a href="listHandling.html#deep-and-flat-lists">Deep and Flat Lists</a></li>
<li title="Recursive List Functions"><a href="listHandling.html#recursive-list-functions">Recursive List Functions</a></li>
</ul>
</li>
<li id="no" title="Functions" expanded="false">Functions<ul>
<li><a href="functions.html">
Top of chapter
</a></li>
<li title="Pattern Matching"><a href="functions.html#pattern-matching">Pattern Matching</a></li>
<li title="Function Calls"><a href="functions.html#function-calls">Function Calls</a></li>
<li title="Memory Usage in Recursion"><a href="functions.html#memory-usage-in-recursion">Memory Usage in Recursion</a></li>
</ul>
</li>
<li id="no" title="Tables and Databases" expanded="false">Tables and Databases<ul>
<li><a href="tablesDatabases.html">
Top of chapter
</a></li>
<li title="Ets, Dets, and Mnesia"><a href="tablesDatabases.html#ets,-dets,-and-mnesia">Ets, Dets, and Mnesia</a></li>
<li title="Ets-Specific"><a href="tablesDatabases.html#ets-specific">Ets-Specific</a></li>
<li title="Mnesia-Specific"><a href="tablesDatabases.html#mnesia-specific">Mnesia-Specific</a></li>
</ul>
</li>
<li id="no" title="Processes" expanded="false">Processes<ul>
<li><a href="processes.html">
Top of chapter
</a></li>
<li title="Creating an Erlang Process"><a href="processes.html#creating-an-erlang-process">Creating an Erlang Process</a></li>
<li title="Process Messages"><a href="processes.html#process-messages">Process Messages</a></li>
<li title="SMP Emulator"><a href="processes.html#smp-emulator">SMP Emulator</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Drivers" expanded="true">Drivers<ul>
<li><a href="drivers.html">
Top of chapter
</a></li>
<li title="Drivers and Concurrency"><a href="drivers.html#drivers-and-concurrency">Drivers and Concurrency</a></li>
<li title="Avoiding Copying Binaries When Calling a Driver"><a href="drivers.html#avoiding-copying-binaries-when-calling-a-driver">Avoiding Copying Binaries When Calling a Driver</a></li>
<li title="Returning Small Binaries from a Driver"><a href="drivers.html#returning-small-binaries-from-a-driver">Returning Small Binaries from a Driver</a></li>
<li title="Returning Large Binaries without Copying from a Driver"><a href="drivers.html#returning-large-binaries-without-copying-from-a-driver">Returning Large Binaries without Copying from a Driver</a></li>
</ul>
</li>
<li id="no" title="Advanced" expanded="false">Advanced<ul>
<li><a href="advanced.html">
Top of chapter
</a></li>
<li title="Memory"><a href="advanced.html#memory">Memory</a></li>
<li title="System Limits"><a href="advanced.html#system-limits">System Limits</a></li>
</ul>
</li>
<li id="no" title="Profiling" expanded="false">Profiling<ul>
<li><a href="profiling.html">
Top of chapter
</a></li>
<li title="Do Not Guess About Performance - Profile"><a href="profiling.html#do-not-guess-about-performance---profile">Do Not Guess About Performance - Profile</a></li>
<li title="Memory profiling"><a href="profiling.html#memory-profiling">Memory profiling</a></li>
<li title="Large Systems"><a href="profiling.html#large-systems">Large Systems</a></li>
<li title="What to Look For"><a href="profiling.html#what-to-look-for">What to Look For</a></li>
<li title="Tools"><a href="profiling.html#tools">Tools</a></li>
<li title="Benchmarking"><a href="profiling.html#benchmarking">Benchmarking</a></li>
</ul>
</li>
<li id="no" title="Retired Myths" expanded="false">Retired Myths<ul>
<li><a href="retired_myths.html">
Top of chapter
</a></li>
<li title="Myth: Funs are Slow"><a href="retired_myths.html#myth--funs-are-slow">Myth: Funs are Slow</a></li>
<li title="Myth: List Comprehensions are Slow"><a href="retired_myths.html#myth--list-comprehensions-are-slow">Myth: List Comprehensions are Slow</a></li>
<li title='Myth: List subtraction ("--" operator) is slow'><a href="retired_myths.html#myth--list-subtraction-------operator--is-slow">Myth: List subtraction ("--" operator) is slow</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>9 Drivers</h1>
<p>This section provides a brief overview on how to write efficient
drivers.</p>
<p>It is assumed that you have a good understanding of drivers.</p>
<h3><span onMouseOver="document.getElementById('ghlink-drivers-and-concurrency-idm281472395912088').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-drivers-and-concurrency-idm281472395912088').style.visibility = 'hidden';"><span id="ghlink-drivers-and-concurrency-idm281472395912088" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/system/doc/efficiency_guide/drivers.xml#L36" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="drivers-and-concurrency" href="#drivers-and-concurrency">9.1
Drivers and Concurrency</a></span></h3>
<p>The runtime system always takes a lock before running
any code in a driver.</p>
<p>By default, that lock is at the driver level, that is,
if several ports have 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 have one lock for each port instead.</p>
<p>If a driver is used in a functional way (that is, 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 as follows:</p>
<div class="example"><pre>-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()).</pre></div>
<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>
<h3><span onMouseOver="document.getElementById('ghlink-avoiding-copying-binaries-when-calling-a-driver-idm281472395907608').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-avoiding-copying-binaries-when-calling-a-driver-idm281472395907608').style.visibility = 'hidden';"><span id="ghlink-avoiding-copying-binaries-when-calling-a-driver-idm281472395907608" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/system/doc/efficiency_guide/drivers.xml#L69" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="avoiding-copying-binaries-when-calling-a-driver" href="#avoiding-copying-binaries-when-calling-a-driver">9.2
Avoiding Copying Binaries When Calling a Driver</a></span></h3>
<p>There are basically two ways to avoid copying a binary that is
sent to a driver:</p>
<ul>
<li>
<p>If the <span class="code">Data</span> argument for
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erlang.html#port_control-3');">port_control/3</a></span>
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 <span class="code">Data</span>
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
extra data to a driver without copying the binary, you must call
<span class="code">port_control/3</span> twice; once with the binary and once with the
extra data. However, that will only work if there is only one
process communicating with the port (because otherwise another process
can call the driver in-between the calls).</p>
</li>
<li><p>Implement an <span class="code">outputv</span> callback (instead of an
<span class="code">output</span> callback) in the driver. If a driver has an
<span class="code">outputv</span> callback, refc binaries passed in an iolist
in the <span class="code">Data</span> argument for
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erlang.html#port_command-2');">port_command/2</a></span>
will be passed as references to the driver.</p></li>
</ul>
<h3><span onMouseOver="document.getElementById('ghlink-returning-small-binaries-from-a-driver-idm281472395898248').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-returning-small-binaries-from-a-driver-idm281472395898248').style.visibility = 'hidden';"><span id="ghlink-returning-small-binaries-from-a-driver-idm281472395898248" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/system/doc/efficiency_guide/drivers.xml#L99" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="returning-small-binaries-from-a-driver" href="#returning-small-binaries-from-a-driver">9.3
Returning Small Binaries from a Driver</a></span></h3>
<p>The runtime system can represent binaries up to 64 bytes as
heap binaries. They are always copied when sent in messages,
but they 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
are advised to use driver API calls that do not require a pre-allocated
binary, for example,
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erl_driver.html#driver_output');">driver_output()</a></span>
or
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erl_driver.html#erl_drv_output_term');">erl_drv_output_term()</a></span>,
using the <span class="code">ERL_DRV_BUF2BINARY</span> format,
to allow the runtime to construct a heap binary.</p>
<h3><span onMouseOver="document.getElementById('ghlink-returning-large-binaries-without-copying-from-a-driver-idm281472395893784').style.visibility = 'visible';" onMouseOut="document.getElementById('ghlink-returning-large-binaries-without-copying-from-a-driver-idm281472395893784').style.visibility = 'hidden';"><span id="ghlink-returning-large-binaries-without-copying-from-a-driver-idm281472395893784" class="ghlink"><a href="https://github.com/erlang/otp/edit/maint/system/doc/efficiency_guide/drivers.xml#L118" title="Found an issue with the documentation? Fix it by clicking here!"><span class="pencil"></span></a></span><a class="title_link" name="returning-large-binaries-without-copying-from-a-driver" href="#returning-large-binaries-without-copying-from-a-driver">9.4
Returning Large Binaries without Copying from a Driver</a></span></h3>
<p>To avoid copying data when a large 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
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erl_driver.html#driver_alloc_binary');">driver_alloc_binary()</a></span>
to allocate a binary.</p>
<p>There are several ways to send a binary created with
<span class="code">driver_alloc_binary()</span>:</p>
<ul>
<li>From the <span class="code">control</span> callback, a binary can be returned if
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erl_driver.html#set_port_control_flags');">set_port_control_flags()</a></span>
has been called with the flag value <span class="code">PORT_CONTROL_FLAG_BINARY</span>.</li>
<li>A single binary can be sent with
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erl_driver.html#driver_output_binary');">driver_output_binary()</a></span>.</li>
<li>Using
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erl_driver.html#erl_drv_output_term');">erl_drv_output_term()</a></span>
or
<span class="bold_code bc-13"><a href="javascript:erlhref('../../','erts','erl_driver.html#erl_drv_send_term');">erl_drv_send_term()</a></span>,
a binary can be included in an Erlang term.</li>
</ul>
</div>
<div class="footer">
<hr>
<p>Copyright © 2001-2019 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div>
<script type="text/javascript">window.__otpTopDocDir = '../js/';</script><script type="text/javascript" src="../js/highlight.js"></script>
</body>
</html>
