summaryrefslogtreecommitdiff
path: root/ref/print.html
diff options
context:
space:
mode:
Diffstat (limited to 'ref/print.html')
-rw-r--r--ref/print.html188
1 files changed, 180 insertions, 8 deletions
diff --git a/ref/print.html b/ref/print.html
index 093edebb..c9ea58f2 100644
--- a/ref/print.html
+++ b/ref/print.html
@@ -1795,7 +1795,7 @@ and returns immediately without waiting. If cancellation was successful,
then <a href="api//api/aio.html#result-of-operation"><code>nng_aio_result</code></a> will return <em>err</em>.</p>
<p>The <a name="a009"></a><code>nng_aio_cancel</code> function acts like <code>nng_aio_abort</code>, but uses the error code
<a href="api//api/errors.html#NNG_ECANCELED"><code>NNG_ECANCELED</code></a><a name="a010"></a>.</p>
-<p>The <a name="a011"></a><code>nng_aio_stop</code> function aborts the <em>aio</em> operation with [<code>NNG_ESTOPPED</code>],
+<p>The <a name="a011"></a><code>nng_aio_stop</code> function aborts the <em>aio</em> operation with <a href="api//api/errors.html#NNG_ESTOPPED"><code>NNG_ESTOPPED</code></a>,
and then waits the operation and any associated callback to complete.
This function also marks <em>aio</em> itself permanently stopped, so that any
new operations scheduled by I/O providers using <a href="api//TODO.html"><code>nng_aio_start</code></a>
@@ -1958,9 +1958,31 @@ return <code>NULL</code>.</p>
<p>It is an error to call this function while the <em>aio</em> is currently
in use by an active asynchronous operation.</p>
</div>
+<h2 id="scatter-gather-vectors"><a class="header" href="#scatter-gather-vectors">Scatter Gather Vectors</a></h2>
+<pre><code class="language-c">typedef struct nng_iov {
+ void *iov_buf;
+ size_t iov_len;
+} nng_iov;
+
+void nng_aio_set_iov(nng_aio *aio, unsigned nio, const nng_iov *iov);
+</code></pre>
+<p><a name="a022"></a>
+Some asynchronous operations, such as those dealing with <a href="api//api/stream.html">streams</a>, use <a name="a023"></a>scatter or <a name="a024"></a>gather
+vectors, where data to be transferred is either gathered from multiple separate regions of memory, or
+scattered into separate regions of memory. For example a message may have a header located at one location
+in memory, and a payload located in another.</p>
+<p>The <a name="a025"></a><code>nng_aio_set_iov</code> function configures the <em>aio</em> to use <em>nio</em> separate segments, described by
+the elements in <em>iov</em>. For each of these, the segment of size <em>iov_len</em> located at <em>iov_buf</em> will be used.</p>
+<p>The elements of <em>iov</em> will be copied into <em>aio</em>, so the vector may be located
+on the stack or another temporary location. The locations referenced by it, <em>must</em> remain valid for
+the duration of the operation, of course.</p>
+<p>Note that many of these operations are not guaranteed to perform a full transfer of data, so even a
+successful operation should check the amount of data actually transferred using <a href="api//api/aio.html#result-of-operation"><code>nng_aio_count</code></a>,
+and if necessary resubmit the operation with a suitably updated vector of <code>nng_iov</code> using this function.</p>
<h2 id="see-also-2"><a class="header" href="#see-also-2">See Also</a></h2>
<p><a href="api//api/synch.html">Synchronization</a>,
<a href="api//api/thread.html">Threads</a>,
+<a href="api//api/stream.html">Streams</a>,
<a href="api//api/time.html">Time</a></p>
<!-- Symbol cross reference -->
<!-- Macros -->
@@ -2167,15 +2189,15 @@ condition_true = true;
nng_cv_wake(cv);
nng_mtx_unlock(m);
</code></pre>
+<h2 id="see-also-3"><a class="header" href="#see-also-3">See Also</a></h2>
+<p><a href="api//api/thread.html">Threads</a>,
+<a href="api//api/time.html">Time</a>,
+<a href="api//api/aio.html">Asynchronous I/O</a></p>
<!-- Symbol cross reference -->
<!-- Macros -->
<!-- Protocols -->
<!-- Transports -->
<!-- Concept index -->
-<h2 id="see-also-3"><a class="header" href="#see-also-3">See Also</a></h2>
-<p><a href="api//api/thread.html">Threads</a>,
-<a href="api//api/time.html">Time</a>,
-<a href="api//api/aio.html">Asynchronous I/O</a></p>
<div style="break-before: page; page-break-before: always;"></div><style>
.mdbook-alerts {
padding: 8px 16px;
@@ -2983,6 +3005,147 @@ which behave the same way, but <em>NNG</em> does not use a separate
}
</style>
+<h1 id="streams"><a class="header" href="#streams">Streams</a></h1>
+<p>NNG provides a common <a name="a001"></a>streams API for working with byte-oriented streams. In NNG, streams are bidirectional
+connections for exchanging a stream of bytes.</p>
+<p>Some common examples of streams are TCP connections, UNIX domain sockets, Windows named pipes, and WebSockets.</p>
+<p>The API documented here is to facilitate applications that wish to work with these at a lower-level than
+Scalability Protocols, in a way that is both portable and agnostic about the specific underlying transport mechanism.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+ <span class="mdbook-alerts-icon"></span>
+ tip
+</p>
+<p>When working with Scalability Protocols directly, it is unlikely that there will be any need for
+using these Streams APIs.</p>
+</div>
+<h2 id="stream-type"><a class="header" href="#stream-type">Stream Type</a></h2>
+<pre><code class="language-c">typedef struct nng_stream nng_stream`
+</code></pre>
+<p>The base <a name="a002"></a><code>nng_stream</code> type represents a bidirectional, byte-oriented, reliable connection.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+ <span class="mdbook-alerts-icon"></span>
+ note
+</p>
+<p>The <code>nng_stream</code> object is used for raw byte stream connections, and
+should not be confused with a <a href="api//TODO.html">pipe</a> object created on a <a href="api//TODO.html">socket</a> using
+the [<code>nng_listen</code>], [<code>nng_dial</code>] or related functions.</p>
+</div>
+<h2 id="sending-and-receiving-data"><a class="header" href="#sending-and-receiving-data">Sending and Receiving Data</a></h2>
+<pre><code class="language-c">void nng_stream_send(nng_stream *s, nng_aio *aio);
+void nng_stream_recv(nng_stream *s, nng_aio *aio);
+</code></pre>
+<p>The <a name="a003"></a><code>nng_stream_send</code> function starts sending data asynchronously over the stream <em>s</em>.
+The data is sent from the scatter/gather vector located in the <a href="api//api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>,
+which must have been previously set using <a href="api//api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>.</p>
+<p>The <a name="a004"></a><code>nng_stream_recv</code> function starts receiving data [asynchronously over the stream <em>s</em>
+into the scatter/gather vector located in the <a href="api//api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>,
+which must have been previously set using <a href="api//api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>.</p>
+<p>These functions return immediately, with no return value.
+Completion of the operation is signaled via the <em>aio</em>, and the final
+result may be obtained via <a href="api//api/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p>
+<p>The I/O operation may complete as soon as at least one byte has been
+transferred, or an error has occurred.
+Therefore, the number of bytes transferred may be less than requested.
+The actual number of bytes transferred can be determined with <a href="api//api/aio.html#result-of-operation"><code>nng_aio_count</code></a>.</p>
+<h2 id="closing-a-stream"><a class="header" href="#closing-a-stream">Closing a Stream</a></h2>
+<pre><code class="language-c">void nng_stream_close(nng_stream *s);
+void nng_stream_stop(nng_stream *s);
+void nng_stream_free(nng_stream *s);
+</code></pre>
+<p>The <a name="a005"></a><code>nng_stream_close</code> function closes a stream, but does not destroy it.
+This function returns immediately. Operations that are pending against the stream, such
+as <a href="api//api/stream.html#sending-and-receiving-data"><code>nng_stream_send</code></a> or <a href="api//api/stream.html#sending-and-receiving-data"><code>nng_stream_recv</code></a> operations will be canceled asynchronously, if possible.
+Those operations will result in <a href="api//api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.</p>
+<p>The <a name="a006"></a><code>nng_stream_stop</code> function not only closes the stream, but waits for any operations
+pending against it to complete, and for any underlying asynchronous registered I/O to be fully deregistered.
+As some systems use separate threads for asynchronous I/O, stopping the stream is necessary before those
+resources can be freed. Until the stream is stopped, there could still be I/O operations in flight,
+making it unsafe to deallocate memory.</p>
+<p>The <a name="a007"></a><code>nng_stream_free</code> function stops the stream like <code>nng_stream_stop</code>, but also deallocates the
+stream itself.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+ <span class="mdbook-alerts-icon"></span>
+ note
+</p>
+<p>Because <code>nng_stream_stop</code> and <code>nng_stream_free</code> both may block waiting for outstanding I/O to complete
+or be aborted, these functions are unsafe to call from functions that may not block, such as the
+completion function registered with an <a href="api//api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> when it is created.</p>
+</div>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
+<div style="break-before: page; page-break-before: always;"></div><style>
+.mdbook-alerts {
+ padding: 8px 16px;
+ margin-bottom: 16px;
+ border-left: 0.25em solid var(--mdbook-alerts-color);
+}
+
+.mdbook-alerts > *:first-child {
+ margin-top: 0;
+}
+
+.mdbook-alerts > *:last-child {
+ margin-bottom: 0;
+}
+
+.mdbook-alerts-title {
+ display: flex;
+ font-weight: 600;
+ align-items: center;
+ line-height: 1;
+ color: var(--mdbook-alerts-color);
+ text-transform: capitalize;
+}
+
+.mdbook-alerts-icon {
+ display: inline-block;
+ width: 1em;
+ height: 1em;
+ margin-right: 0.2em;
+ background-color: currentColor;
+ -webkit-mask: no-repeat center / 100%;
+ mask: no-repeat center / 100%;
+ -webkit-mask-image: var(--mdbook-alerts-icon);
+ mask-image: var(--mdbook-alerts-icon);
+}
+
+.mdbook-alerts-note {
+ --mdbook-alerts-color: rgb(9, 105, 218);
+ /* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
+ --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-tip {
+ --mdbook-alerts-color: rgb(26, 127, 55);
+ /* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
+ --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-important {
+ --mdbook-alerts-color: rgb(130, 80, 223);
+ /* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
+ --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-warning {
+ --mdbook-alerts-color: rgb(154, 103, 0);
+ /* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
+ --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
+}
+
+.mdbook-alerts-caution {
+ --mdbook-alerts-color: rgb(207, 34, 46);
+ /* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
+ --mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
+}
+
+</style>
<h1 id="miscellaneous"><a class="header" href="#miscellaneous">Miscellaneous</a></h1>
<p>This chapter discusses some interfaces that don’t really
fit anywhere else.</p>
@@ -5617,7 +5780,7 @@ See the <a href="migrate/nanomsg.html">Migrating From libnanomsg</a> chapter for
<p>It is now required for applications to initialize the library explicitly before using it.
This is done using the <a href="migrate//api/init.html#initialization"><code>nng_init</code></a> function.</p>
<h2 id="new-aio-error-code-nng_estopped"><a class="header" href="#new-aio-error-code-nng_estopped">New AIO Error Code NNG_ESTOPPED</a></h2>
-<p>When an operation fails with [<code>NNG_ESTOPPED</code>], it means that the associated [<code>nni_aio</code>] object has
+<p>When an operation fails with <a href="migrate//api/errors.html#NNG_ESTOPPED"><code>NNG_ESTOPPED</code></a>, it means that the associated [<code>nni_aio</code>] object has
been permanently stopped and must not be reused. Applications must watch for this error code, and
not resubmit an operation that returns it. This is particularly important for callbacks that automatically
resubmit operations. Failure to observe this rule will lead to an infinite loop
@@ -6046,6 +6209,7 @@ duration, <a href="api/time.html#a003">1</a><br/>
error message, <a href="api/errors.html#a002">1</a><br/>
event loop, <a href="api/sock.html#a009">1</a><br/>
flow control, <a href="proto/index.html#a006">1</a><br/>
+gather, <a href="api/aio.html#a024">1</a><br/>
<code>getopt</code>, <a href="api/cmd_opts.html#a003">1</a><br/>
half-duplex, <a href="proto/index.html#a004">1</a><br/>
header, <a href="api/msg.html#a003">1</a><br/>
@@ -6080,7 +6244,7 @@ named pipes, <a href="tran/ipc.html#a004">1</a><br/>
<code>nng_aio_reap</code>, <a href="api/aio.html#a007">1</a><br/>
<code>nng_aio_result</code>, <a href="api/aio.html#a016">1</a><br/>
<code>nng_aio_set_expire</code>, <a href="api/aio.html#a013">1</a><br/>
-<code>nng_aio_set_iov</code>, <a href="api/aio.html#a021">1</a><br/>
+<code>nng_aio_set_iov</code>, <a href="api/aio.html#a021">1</a>, <a href="api/aio.html#a025">2</a><br/>
<code>nng_aio_set_msg</code>, <a href="api/aio.html#a019">1</a><br/>
<code>nng_aio_stop</code>, <a href="api/aio.html#a011">1</a><br/>
<code>nng_aio_wait</code>, <a href="api/aio.html#a014">1</a><br/>
@@ -6109,7 +6273,7 @@ named pipes, <a href="tran/ipc.html#a004">1</a><br/>
<code>nng_id_remove</code>, <a href="api/id_map.html#a007">1</a><br/>
<code>nng_id_visit</code>, <a href="api/id_map.html#a008">1</a><br/>
<code>nng_init</code>, <a href="api/init.html#a001">1</a><br/>
-<code>nng_iov</code>, <a href="api/aio.html#a020">1</a><br/>
+<code>nng_iov</code>, <a href="api/aio.html#a020">1</a>, <a href="api/aio.html#a022">2</a><br/>
<code>nng_log</code>, <a href="api/logging.html#a001">1</a><br/>
<code>nng_log_auth</code>, <a href="api/logging.html#a002">1</a><br/>
<code>nng_log_get_level</code>, <a href="api/logging.html#a005">1</a><br/>
@@ -6196,6 +6360,12 @@ named pipes, <a href="tran/ipc.html#a004">1</a><br/>
<code>nng_stats_get</code>, <a href="api/stats.html#a003">1</a><br/>
<code>nng_stderr_logger</code>, <a href="api/logging.html#a011">1</a><br/>
<code>nng_strdup</code>, <a href="api/memory.html#a005">1</a><br/>
+<code>nng_stream</code>, <a href="api/stream.html#a002">1</a><br/>
+<code>nng_stream_close</code>, <a href="api/stream.html#a005">1</a><br/>
+<code>nng_stream_free</code>, <a href="api/stream.html#a007">1</a><br/>
+<code>nng_stream_recv</code>, <a href="api/stream.html#a004">1</a><br/>
+<code>nng_stream_send</code>, <a href="api/stream.html#a003">1</a><br/>
+<code>nng_stream_stop</code>, <a href="api/stream.html#a006">1</a><br/>
<code>nng_strerror</code>, <a href="api/errors.html#a001">1</a><br/>
<code>nng_strfree</code>, <a href="api/memory.html#a006">1</a><br/>
<code>nng_system_logger</code>, <a href="api/logging.html#a012">1</a><br/>
@@ -6243,12 +6413,14 @@ random number, <a href="api/misc.html#a002">1</a><br/>
request/reply pattern, <a href="proto/rep.html#a003">1</a>, <a href="proto/req.html#a003">2</a>, <a href="proto/index.html#a002">3</a><br/>
<em>RESPONDENT</em>, <a href="proto/respondent.html#a002">1</a><br/>
<em>RESPONDENT</em> protocol, <a href="proto/respondent.html#a001">1</a><br/>
+scatter, <a href="api/aio.html#a023">1</a><br/>
scheduling, <a href="api/time.html#a010">1</a><br/>
service discovery, <a href="proto/surveyor.html#a006">1</a><br/>
socket, <a href="api/sock.html#a001">1</a><br/>
<em>socket</em> transport, <a href="tran/socket.html#a001">1</a><br/>
<code>socket://</code>, <a href="tran/socket.html#a003">1</a><br/>
statistics, <a href="api/stats.html#a001">1</a><br/>
+streams, <a href="api/stream.html#a001">1</a><br/>
<em>SUB</em>, <a href="proto/sub.html#a002">1</a><br/>
<em>SUB</em> protocol, <a href="proto/sub.html#a001">1</a><br/>
subscriber, <a href="proto/sub.html#a003">1</a><br/>
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2026-01-26 08:20:43 +0000