path: root/man/tip/nng_device.3.html

---
version: tip
layout: manpage_v2
title: nng_device(3)
---
<h1>nng_device(3)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_device - message forwarding device</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/nng.h&gt;</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_device</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s1</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s2</span><span class="tok-p">);</span>

<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_device_aio</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s1</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s2</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>nng_device()</code> and <code>nng_device_aio()</code> functions forward messages received from one
<a href="nng_socket.5.html">socket</a> <em>s1</em> to another socket <em>s2</em>, and vice versa.</p>
</div>
<div class="paragraph">
<p>These functions are used to create forwarders, which can be used to create
complex network topologies to provide for improved horizontal scalability,
reliability, and isolation.</p>
</div>
<div class="paragraph">
<p>Only <a href="nng_options.5.html#NNG_OPT_RAW">raw</a> mode sockets may be used with this
function.
These can be created using <code>_raw</code> forms of the various socket constructors,
such as <a href="nng_req_open.3.html"><code>nng_req0_open_raw()</code></a>.</p>
</div>
<div class="paragraph">
<p>The <code>nng_device()</code> function does not return until one of the sockets
is closed.
The <code>nng_device_aio()</code> function returns immediately, and operates completely in
the background.</p>
</div>
<div class="sect2">
<h3 id="_reflectors">Reflectors</h3>
<div class="paragraph">
<p>One of the sockets passed may be an unopened socket initialized with
the <code>NNG_SOCKET_INITIALIZER</code> special value.
If this is the case, then the other socket must be valid, and must use
a protocol that is bidirectional and can peer with itself (such as
<a href="nng_pair.7.html"><em>pair</em></a> or
<a href="nng_bus.7.html"><em>bus</em></a>.)
In this case the device acts as a reflector or loop-back device,
where messages received from the valid socket are merely returned
to the sender.</p>
</div>
</div>
<div class="sect2">
<h3 id="_forwarders">Forwarders</h3>
<div class="paragraph">
<p>When both sockets are valid, then the result is a forwarder or proxy.
In this case sockets <em>s1</em> and <em>s2</em> must be compatible with each other,
which is to say that they should represent the opposite halves of a two
protocol pattern, or both be the same protocol for a single protocol
pattern.
For example, if <em>s1</em> is a <a href="nng_pub.7.html"><em>pub</em></a> socket, then <em>s2</em> must
be a <a href="nng_sub.7.html"><em>sub</em></a> socket.
Or, if <em>s1</em> is a <a href="nng_bus.7.html"><em>bus</em></a> socket, then <em>s2</em> must also
be a <em>bus</em> socket.</p>
</div>
</div>
<div class="sect2">
<h3 id="_operation">Operation</h3>
<div class="paragraph">
<p>The <code>nng_device()</code> function moves messages between the provided sockets.</p>
</div>
<div class="paragraph">
<p>When a protocol has a backtrace style header, routing information
is present in the header of received messages, and is copied to the
header of the output bound message.
The underlying raw mode protocols supply the necessary header
adjustments to add or remove routing headers as needed.
This allows replies to be
returned to requesters, and responses to be routed back to surveyors.</p>
</div>
<div class="paragraph">
<p>The caller of these functions is required to close the sockets when the
device is stopped.</p>
</div>
<div class="paragraph">
<p>Additionally, some protocols have a maximum time-to-live to protect
against forwarding loops and especially amplification loops.
In these cases, the default limit (usually 8), ensures that messages will
self-terminate when they have passed through too many forwarders,
protecting the network from unlimited message amplification that can arise
through misconfiguration.
This is controlled via the <a href="nng_options.5.html#NNG_OPT_MAXTTL"><code>NNG_OPT_MAXTTL</code></a>
option.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Not all protocols have support for guarding against forwarding loops,
and even for those that do, forwarding loops can be extremely detrimental
to network performance.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Devices (forwarders and reflectors) act in best-effort delivery mode only.
If a message is received from one socket that cannot be accepted by the
other (due to backpressure or other issues), then the message is discarded.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Use the request/reply pattern, which includes automatic retries by
the requester, if reliable delivery is needed.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_return_values">RETURN VALUES</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This function continues running, and only returns an appropriate error when
one occurs, or if one of the sockets is closed.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_errors">ERRORS</h2>
<div class="sectionbody">
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<code>NNG_ECLOSED</code>
</td>
<td class="hdlist2">
<p>At least one of the sockets is not open.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_ENOMEM</code>
</td>
<td class="hdlist2">
<p>Insufficient memory is available.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
<code>NNG_EINVAL</code>
</td>
<td class="hdlist2">
<p>The sockets are not compatible, or are both invalid.</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="nng_options.5.html">nng_options(5)</a>,
<a href="nng_socket.5.html">nng_socket(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>