summaryrefslogtreecommitdiff
path: root/ref/print.html
diff options
context:
space:
mode:
Diffstat (limited to 'ref/print.html')
-rw-r--r--ref/print.html172
1 files changed, 97 insertions, 75 deletions
diff --git a/ref/print.html b/ref/print.html
index a8344191..7e930187 100644
--- a/ref/print.html
+++ b/ref/print.html
@@ -984,6 +984,49 @@ The value stored in <em>name</em> is a fixed string located in program text, and
or altered. It is guaranteed to remain valid while this library is present.</p>
<p>The <a name="a008"></a><code>nng_socket_raw</code> function determines whether the socket is in
<a href="api//TODO.html">raw mode</a> or not, storing <code>true</code> in <em>raw</em> if it is, or <code>false</code> if it is not.</p>
+<h2 id="polling-socket-events"><a class="header" href="#polling-socket-events">Polling Socket Events</a></h2>
+<pre><code class="language-c">int nng_socket_get_recv_poll_fd(nng_socket s, int *fdp);
+int nng_socket_get_send_poll_fd(nng_socket s, int *fdp);
+</code></pre>
+<p>Sometimes it is necessary to integrate a socket into a <code>poll</code> or <code>select</code> driven
+<a name="a009"></a>event loop. (Or, on Linux, <code>epoll</code>, or on BSD derived systems like macOS <code>kqueue</code>).</p>
+<p>For these occasions, a suitable file descriptor for polling is provided
+by these two functions.</p>
+<p>The <a name="a010"></a><code>nng_socket_get_recv_poll_fd</code> function obtains a file descriptor
+that will poll as readable when a message is ready for receiving for the socket.</p>
+<p>The <a name="a011"></a><code>nng_socket_get_send_poll_fd</code> function obtains a file descriptor
+that will poll as readable when the socket can accept a message for sending.</p>
+<p>These file descriptors should only be polled for readability, and no
+other operation performed on them. The socket will read from, or write to,
+these file descriptors to provide a level-signaled behavior automatically.</p>
+<p>Additionally the socket will close these file descriptors when the socket itself is closed.</p>
+<p>These functions replace the <code>NNG_OPT_SENDFD</code> and <code>NNG_OPT_RECVFD</code> socket options that
+were available in previous versions of NNG.</p>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+ <span class="mdbook-alerts-icon"></span>
+ note
+</p>
+<p>These functions are not compatible with <a href="api//TODO.html">contexts</a>.</p>
+</div>
+<div class="mdbook-alerts mdbook-alerts-note">
+<p class="mdbook-alerts-title">
+ <span class="mdbook-alerts-icon"></span>
+ note
+</p>
+<p>The file descriptors supplied by these functions is not used for transporting message data.
+The only valid use of these file descriptors is for polling for the ability to send or receive
+messages on the socket.</p>
+</div>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+ <span class="mdbook-alerts-icon"></span>
+ tip
+</p>
+<p>Using these functions will force the socket to perform extra system calls, and thus
+have a negative impact on performance and latency. It is preferable to use <a href="api//api/aio.html">asynchronous I/O</a>
+when possible.</p>
+</div>
<h2 id="examples-1"><a class="header" href="#examples-1">Examples</a></h2>
<h3 id="example-1-initializing-a-socket"><a class="header" href="#example-1-initializing-a-socket">Example 1: Initializing a Socket</a></h3>
<pre><code class="language-c">nng_socket s = NNG_SOCKET_INITIALIZER;
@@ -1914,28 +1957,28 @@ does not depend on <em>which</em> thread will be woken. When in doubt, <code>nng
</div>
<h2 id="examples-2"><a class="header" href="#examples-2">Examples</a></h2>
<h3 id="example-1-allocating-the-condition-variable"><a class="header" href="#example-1-allocating-the-condition-variable">Example 1: Allocating the condition variable</a></h3>
-<pre><code class="language-c"> nng_mtx *m;
- nng_cv *cv;
- nng_mtx_alloc(&amp;m); // error checks elided
- nng_cv_alloc(&amp;cv, m);
+<pre><code class="language-c">nng_mtx *m;
+nng_cv *cv;
+nng_mtx_alloc(&amp;m); // error checks elided
+nng_cv_alloc(&amp;cv, m);
</code></pre>
<h3 id="example-2-waiting-for-the-condition"><a class="header" href="#example-2-waiting-for-the-condition">Example 2: Waiting for the condition</a></h3>
-<pre><code class="language-c"> expire = nng_clock() + 1000; // 1 second in the future
- nng_mtx_lock(m); // assume cv was allocated using m
- while (!condition_true) {
- if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
- printf("Time out reached!\n");
- break;
- }
- }
- // condition_true is true
- nng_mtx_unlock(m);
+<pre><code class="language-c">expire = nng_clock() + 1000; // 1 second in the future
+nng_mtx_lock(m); // assume cv was allocated using m
+while (!condition_true) {
+ if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
+ printf("Time out reached!\n");
+ break;
+ }
+}
+// condition_true is true
+nng_mtx_unlock(m);
</code></pre>
<h3 id="example-3-signaling-the-condition"><a class="header" href="#example-3-signaling-the-condition">Example 3: Signaling the condition</a></h3>
-<pre><code class="language-c"> nng_mtx_lock(m);
- condition_true = true;
- nng_cv_wake(cv);
- nng_mtx_unlock(m);
+<pre><code class="language-c">nng_mtx_lock(m);
+condition_true = true;
+nng_cv_wake(cv);
+nng_mtx_unlock(m);
</code></pre>
<!-- Symbol cross reference -->
<!-- Macros -->
@@ -2225,12 +2268,12 @@ set by <code>nng_log_set_level</code> or the default
if that function has not been called.</p>
<p>The log levels are defined as follows:</p>
<pre><code class="language-c">typedef enum nng_log_level {
- NNG_LOG_NONE = 0, // used for filters only, NNG suppresses these
- NNG_LOG_ERR = 3,
- NNG_LOG_WARN = 4,
- NNG_LOG_NOTICE = 5,
- NNG_LOG_INFO = 6,
- NNG_LOG_DEBUG = 7
+ NNG_LOG_NONE = 0, // used for filters only, NNG suppresses these
+ NNG_LOG_ERR = 3,
+ NNG_LOG_WARN = 4,
+ NNG_LOG_NOTICE = 5,
+ NNG_LOG_INFO = 6,
+ NNG_LOG_DEBUG = 7
} nng_log_level;
</code></pre>
<p>The value <code>NNG_LOG_NONE</code> may be useful to suppress message logs altogether.</p>
@@ -2247,17 +2290,17 @@ Traditionally these are used with the UNIX <code>syslog</code> system, and
the values here represent some (but not all) of the values found there.</p>
<p>The following values are defined:</p>
<pre><code class="language-c">typedef enum nng_log_facility {
- NNG_LOG_USER = 1,
- NNG_LOG_DAEMON = 3,
- NNG_LOG_AUTH = 10,
- NNG_LOG_LOCAL0 = 16,
- NNG_LOG_LOCAL1 = 17,
- NNG_LOG_LOCAL2 = 18,
- NNG_LOG_LOCAL3 = 19,
- NNG_LOG_LOCAL4 = 20,
- NNG_LOG_LOCAL5 = 21,
- NNG_LOG_LOCAL6 = 22,
- NNG_LOG_LOCAL7 = 23,
+ NNG_LOG_USER = 1,
+ NNG_LOG_DAEMON = 3,
+ NNG_LOG_AUTH = 10,
+ NNG_LOG_LOCAL0 = 16,
+ NNG_LOG_LOCAL1 = 17,
+ NNG_LOG_LOCAL2 = 18,
+ NNG_LOG_LOCAL3 = 19,
+ NNG_LOG_LOCAL4 = 20,
+ NNG_LOG_LOCAL5 = 21,
+ NNG_LOG_LOCAL6 = 22,
+ NNG_LOG_LOCAL7 = 23,
} nng_log_facility;
</code></pre>
<p>The <a name="a006"></a><code>nng_log_set_facility</code> function can be used to
@@ -4421,42 +4464,14 @@ Attempts to send messages will result in <code>NNG_ENOTSUP</code>.</p>
<p>Only version 0 of this protocol is supported.
(At the time of writing, no other versions of this protocol have been defined.)</p>
<h3 id="protocol-options-8"><a class="header" href="#protocol-options-8">Protocol Options</a></h3>
-<p>The following protocol-specific options are available.</p>
+<p>The following protocol-specific option is available.</p>
<ul>
-<li>
-<p><a name="a004"></a><code>NNG_OPT_SUB_SUBSCRIBE</code><a name="a005"></a>: <br />
-<br />
-This option registers a topic that the subscriber is interested in.
-The option is write-only, and takes an array of bytes, of arbitrary size.
-Each incoming message is checked against the list of subscribed topics.
-If the body begins with the entire set of bytes in the topic, then the
-message is accepted. If no topic matches, then the message is
-discarded. <br />
-<br />
-This option is a byte array. Thus if you use
-<a href="proto/TODO.html"><code>nng_socket_set_string</code></a> the <code>NUL</code> terminator byte will
-be included in the topic.
-If that isn’t desired, consider using
-<a href="proto/TODO.html"><code>nng_socket_set</code></a> and using <code>strlen</code> of the topic
-as the topic size. <br />
-<br />
-To receive all messages, an empty topic (zero length) can be used.</p>
-</li>
-<li>
-<p><a name="a006"></a><code>NNG_OPT_SUB_UNSUBSCRIBE</code>: <br />
-<br />
-This option, also read-only, removes a topic from the subscription list.
-Note that if the topic was not previously subscribed to with
-<code>NNG_OPT_SUB_SUBSCRIBE</code> then an <code>NNG_ENOENT</code> error will result.</p>
-</li>
-<li>
-<p><a name="a007"></a><code>NNG_OPT_SUB_PREFNEW</code>: <br />
+<li><a name="a004"></a><code>NNG_OPT_SUB_PREFNEW</code>: <br />
(<code>bool</code>) <br />
<br />
This read/write option specifies the behavior of the subscriber when the queue is full.
When <code>true</code> (the default), the subscriber will make room in the queue by removing the oldest message.
-When <code>false</code>, the subscriber will reject messages if the message queue does not have room.</p>
-</li>
+When <code>false</code>, the subscriber will reject messages if the message queue does not have room.</li>
</ul>
<h3 id="protocol-headers-8"><a class="header" href="#protocol-headers-8">Protocol Headers</a></h3>
<p>The <em>SUB</em> protocol has no protocol-specific headers.</p>
@@ -5482,20 +5497,27 @@ before bringing them into the socket itself.</p>
<h2 id="socket-options"><a class="header" href="#socket-options">Socket Options</a></h2>
<p>The <code>NNG_OPT_PROTO</code>, <code>NNG_OPT_PROTONAME</code>, <code>NNG_OPT_PEER</code>, and <code>NNG_OPT_PEERNAME</code> options
have been replaced by functions instead of options.
-Use <code>nng_socket_proto_id</code>, <code>nng_socket_peer_id</code>, <code>nng_socket_proto_name</code>, and <code>nng_socket_peer_name</code> instead.
+Use <a href="migrate//api/sock.html#socket-identity"><code>nng_socket_proto_id</code></a>, <a href="migrate//api/sock.html#socket-identity"><code>nng_socket_peer_id</code></a>, <a href="migrate//api/sock.html#socket-identity"><code>nng_socket_proto_name</code></a>, and <a href="migrate//api/sock.html#socket-identity"><code>nng_socket_peer_name</code></a> instead.
Note that the new functions provide a reference to a static string, and thus do not require
allocation, and the returned strings should not be freed. Also the IDs are provided as <code>uint16_t</code>,
matching the actual wire protocol values, instead of <code>int</code>.</p>
-<p>The <code>NNG_OPT_RAW</code> option has aso been replaced by a function, <code>nng_socket_raw</code>.</p>
+<p>The <code>NNG_OPT_RAW</code> option has aso been replaced by a function, <a href="migrate//api/sock.html#socket-identity"><code>nng_socket_raw</code></a>.</p>
+<p>The <code>NNG_OPT_SENDFD</code> and <code>NNG_OPT_RECVFD</code> options have been replaced by
+<a href="migrate//api/sock.html#polling-socket-events"><code>nng_socket_get_send_poll_fd</code></a> and <a href="migrate//api/sock.html#polling-socket-events"><code>nng_socket_get_recv_poll_fd</code></a> respectively.</p>
<h2 id="subscriptions"><a class="header" href="#subscriptions">Subscriptions</a></h2>
<p>The <code>NNG_OPT_SUB_SUBSCRIBE</code> and <code>NNG_OPT_SUB_UNSUBCRIBE</code> options have been replaced by
-the following functions: <code>nng_sub0_socket_subscribe</code>, <code>nng_sub0_socket_unsubscribe</code>,
-<code>nng_sub0_ctx_subscribe</code> and <code>nng_sub0_ctx_unsubscribe</code>. These functions, like the options
+the following functions: <a href="migrate//TODO.html"><code>nng_sub0_socket_subscribe</code></a>, <a href="migrate//TODO.html"><code>nng_sub0_socket_unsubscribe</code></a>,
+<a href="migrate//TODO.html"><code>nng_sub0_ctx_subscribe</code></a> and <a href="migrate//TODO.html"><code>nng_sub0_ctx_unsubscribe</code></a>. These functions, like the options
they replace, are only applicable to SUB sockets.</p>
<h2 id="statistics-use-constified-pointers"><a class="header" href="#statistics-use-constified-pointers">Statistics Use Constified Pointers</a></h2>
-<p>A number of the statistics functions take, or return, <code>const nng_stat *</code> instead
+<p>A number of the <a href="migrate//api/stats.html">statistics</a> functions take, or return, <code>const nng_stat *</code> instead
of plain <code>nng_stat *</code>. The ABI has not changed, but it may be necessary to declare
certain methods variables <code>const</code> to avoid warnings about misuse of <code>const</code>.</p>
+<!-- Symbol cross reference -->
+<!-- Macros -->
+<!-- Protocols -->
+<!-- Transports -->
+<!-- Concept index -->
<div style="break-before: page; page-break-before: always;"></div><style>
.mdbook-alerts {
padding: 8px 16px;
@@ -5687,6 +5709,7 @@ condition variable, <a href="api/synch.html#a009">1</a><br/>
CPU-bound, <a href="api/thread.html#a003">1</a><br/>
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/>
<code>getopt</code>, <a href="api/cmd_opts.html#a003">1</a><br/>
half-duplex, <a href="proto/index.html#a004">1</a><br/>
@@ -5794,9 +5817,7 @@ named pipes, <a href="tran/ipc.html#a004">1</a><br/>
<code>NNG_OPT_REQ_RESENDTICK</code>, <a href="proto/req.html#a007">1</a><br/>
<code>NNG_OPT_REQ_RESENDTIME</code>, <a href="proto/req.html#a006">1</a><br/>
<code>NNG_OPT_SOCKET_FD</code>, <a href="tran/socket.html#a002">1</a>, <a href="tran/socket.html#a005">2</a><br/>
-<code>NNG_OPT_SUB_PREFNEW</code>, <a href="proto/sub.html#a007">1</a><br/>
-<code>NNG_OPT_SUB_SUBSCRIBE</code>, <a href="proto/sub.html#a004">1</a><br/>
-<code>NNG_OPT_SUB_UNSUBSCRIBE</code>, <a href="proto/sub.html#a006">1</a><br/>
+<code>NNG_OPT_SUB_PREFNEW</code>, <a href="proto/sub.html#a004">1</a><br/>
<code>NNG_OPT_SURVEYOR_SURVEYTIME</code>, <a href="proto/surveyor.html#a007">1</a><br/>
<code>nng_opts_parse</code>, <a href="api/cmd_opts.html#a001">1</a><br/>
<code>nng_optspec</code>, <a href="api/cmd_opts.html#a004">1</a><br/>
@@ -5804,6 +5825,8 @@ named pipes, <a href="tran/ipc.html#a004">1</a><br/>
<code>nng_random</code>, <a href="api/misc.html#a001">1</a><br/>
<code>nng_sleep_aio</code>, <a href="api/time.html#a011">1</a><br/>
<code>nng_socket</code>, <a href="api/sock.html#a002">1</a><br/>
+<code>nng_socket_get_recv_poll_fd</code>, <a href="api/sock.html#a010">1</a><br/>
+<code>nng_socket_get_send_poll_fd</code>, <a href="api/sock.html#a011">1</a><br/>
<code>nng_socket_id</code>, <a href="api/sock.html#a003">1</a><br/>
<code>nng_socket_peer_id</code>, <a href="api/sock.html#a005">1</a><br/>
<code>nng_socket_peer_name</code>, <a href="api/sock.html#a007">1</a><br/>
@@ -5881,7 +5904,6 @@ socket, <a href="api/sock.html#a001">1</a><br/>
statistics, <a href="api/stats.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/>
-subscribe, <a href="proto/sub.html#a005">1</a><br/>
subscriber, <a href="proto/sub.html#a003">1</a><br/>
survey pattern, <a href="proto/respondent.html#a003">1</a>, <a href="proto/surveyor.html#a003">2</a><br/>
<em>SURVEYOR</em>, <a href="proto/surveyor.html#a002">1</a><br/>
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2026-01-26 02:10:57 +0000