diff options
| author | gdamore <gdamore@users.noreply.github.com> | 2025-10-09 01:22:20 +0000 |
|---|---|---|
| committer | gdamore <gdamore@users.noreply.github.com> | 2025-10-09 01:22:20 +0000 |
| commit | edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b (patch) | |
| tree | f3396cdaec643fb87365b5f92df4f92e6644b075 /ref/api | |
| parent | ecdd21b5f4bd29bc1a88d276a9c8015dd100063b (diff) | |
| download | nng-edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b.tar.gz nng-edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b.tar.bz2 nng-edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b.zip | |
deploy: 9c834956456924df7c885ab8b79573721acaff5c
Diffstat (limited to 'ref/api')
| -rw-r--r-- | ref/api/aio.html | 70 | ||||
| -rw-r--r-- | ref/api/args.html | 2 | ||||
| -rw-r--r-- | ref/api/ctx.html | 64 | ||||
| -rw-r--r-- | ref/api/errors.html | 10 | ||||
| -rw-r--r-- | ref/api/http.html | 120 | ||||
| -rw-r--r-- | ref/api/id_map.html | 14 | ||||
| -rw-r--r-- | ref/api/init.html | 6 | ||||
| -rw-r--r-- | ref/api/memory.html | 16 | ||||
| -rw-r--r-- | ref/api/misc.html | 2 | ||||
| -rw-r--r-- | ref/api/msg.html | 20 | ||||
| -rw-r--r-- | ref/api/pipe.html | 18 | ||||
| -rw-r--r-- | ref/api/sock.html | 124 | ||||
| -rw-r--r-- | ref/api/stats.html | 36 | ||||
| -rw-r--r-- | ref/api/stream.html | 62 | ||||
| -rw-r--r-- | ref/api/synch.html | 30 | ||||
| -rw-r--r-- | ref/api/thread.html | 8 | ||||
| -rw-r--r-- | ref/api/time.html | 12 | ||||
| -rw-r--r-- | ref/api/url.html | 8 |
18 files changed, 311 insertions, 311 deletions
diff --git a/ref/api/aio.html b/ref/api/aio.html index e171e0d4..796c6a51 100644 --- a/ref/api/aio.html +++ b/ref/api/aio.html @@ -247,7 +247,7 @@ <p>In order to obtain significant scalability, with low-latency, and minimal overheads, <em>NNG</em> supports performing operations asynchronously.</p> <p>One way that applications can perform work asynchronously and concurrently -is by using <a href="../../api/thread.html">threads</a>, but threads carry significant resource overheads +is by using <a href="../api/thread.html">threads</a>, but threads carry significant resource overheads and frequently there are limits on the number that can easily be created.</p> <p>Additionally, with most network applications, the flow of execution will spend the bulk of its time waiting for traffic from a peer.</p> @@ -272,17 +272,17 @@ can only be used with a single operation at a time.</p> Instead the application registers a callback function to be executed when the operation is complete (whether successfully or not). This callback will be executed exactly once.</p> -<p>The asynchronous I/O framework also supports <a href="../../api/aio.html#cancellation">cancellation</a> of +<p>The asynchronous I/O framework also supports <a href="../api/aio.html#cancellation">cancellation</a> of operations that are already in progress as well setting a maximum -<a href="../../api/aio.html#set-timeout">timeout</a> for them to complete.</p> -<p>It is also possible to initiate an asynchronous operation, and <a href="../../api/aio.html#wait-for-completion">wait</a> for it to +<a href="../api/aio.html#set-timeout">timeout</a> for them to complete.</p> +<p>It is also possible to initiate an asynchronous operation, and <a href="../api/aio.html#wait-for-completion">wait</a> for it to complete, creating a synchronous flow from an asynchronous one.</p> <h2 id="create-handle"><a class="header" href="#create-handle">Create Handle</a></h2> <pre><code class="language-c">nng_err nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg); </code></pre> -<p>The <a name="a004"></a><code>nng_aio_alloc</code> function creates an <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> object, with the +<p>The <a name="a004"></a><code>nng_aio_alloc</code> function creates an <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> object, with the <a name="a005"></a>callback <em>callb</em> taking the argument <em>arg</em>, and returns it in <em>aiop</em>.</p> -<p>If this succeeds, the function returns zero. Otherwise it may return <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p> +<p>If this succeeds, the function returns zero. Otherwise it may return <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -290,15 +290,15 @@ complete, creating a synchronous flow from an asynchronous one.</p> </p> <p>The <em>arg</em> should normally be a structure that contains a pointer to the <em>aiop</em>, or from which it can be located. This allows <em>callb</em> to check the handle for -success using <a href="../../api/aio.html#result-of-operation"><code>nng_aio_result</code></a>, as well access other properties of <em>aiop</em>.</p> +success using <a href="../api/aio.html#result-of-operation"><code>nng_aio_result</code></a>, as well access other properties of <em>aiop</em>.</p> </div> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> tip </p> -<p>The <em>callb</em> may be executed on another <a href="../../api/thread.html">thread</a>, so it may be necessary to use -<a href="../../api/synch.html">synchronization</a> methods in <em>callb</em> to avoid data races.</p> +<p>The <em>callb</em> may be executed on another <a href="../api/thread.html">thread</a>, so it may be necessary to use +<a href="../api/synch.html">synchronization</a> methods in <em>callb</em> to avoid data races.</p> </div> <h2 id="destroy-handle"><a class="header" href="#destroy-handle">Destroy Handle</a></h2> <pre><code class="language-c">void nng_aio_free(nng_aio *aio); @@ -307,7 +307,7 @@ void nng_aio_reap(nng_aio *aio); <p>The <a name="a006"></a><code>nng_aio_free</code> handle destroys the handle <em>aio</em>, waiting for any operations and associated callbacks to complete before doing so.</p> <p>The <a name="a007"></a><code>nng_aio_reap</code> handle destroys the handle <em>aio</em> asynchronously, using a <em>reaper</em> -<a href="../../api/thread.html">thread</a> to do so. It does not wait for the object to be destroyed. Thus this function +<a href="../api/thread.html">thread</a> to do so. It does not wait for the object to be destroyed. Thus this function is safe to call from <em>aio</em>’s own callback.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> @@ -330,13 +330,13 @@ If the operation is successfully canceled or aborted, then the callback will still be called.</p> <p>The <a name="a008"></a><code>nng_aio_abort</code> function aborts the operation associated with <em>aio</em> and returns immediately without waiting. If cancellation was successful, -then <a href="../../api/aio.html#result-of-operation"><code>nng_aio_result</code></a> will return <em>err</em>.</p> +then <a href="../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/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 <a href="../../api/errors.html#NNG_ESTOPPED"><code>NNG_ESTOPPED</code></a>, +<a href="../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 <a href="../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="../../TODO.html"><code>nng_aio_start</code></a> +new operations scheduled by I/O providers using <a href="../TODO.html"><code>nng_aio_start</code></a> return false. Thus this function should be used to teardown operations.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> @@ -345,7 +345,7 @@ return false. Thus this function should be used to teardown operations.</p> </p> <p>When multiple asynchronous I/O handles are in use and need to be deallocated, it is safest to stop all of them using <code>nng_aio_stop</code>, -before deallocating any of them with <a href="../../api/aio.html#destroy-handle"><code>nng_aio_free</code></a>, +before deallocating any of them with <a href="../api/aio.html#destroy-handle"><code>nng_aio_free</code></a>, particularly if the callbacks might attempt to reschedule further operations.</p> </div> <h2 id="set-timeout"><a class="header" href="#set-timeout">Set Timeout</a></h2> @@ -356,15 +356,15 @@ void nng_aio_set_expire(nng_aio *aio, nng_time expiration); for the asynchronous operation associated with <em>aio</em>. This causes a timer to be started when the operation is actually started. If the timer expires before the operation is completed, then it is -<a href="../../api/aio.html#cancellation">aborted</a> with an error of <code>NNG_ETIMEDOUT</code>. -The <em>timeout</em> <a href="../../api/time.html">duration</a> is specified as a relative number of milliseconds.</p> -<p>If the timeout is <a href="../../api/time.html#duration-type"><code>NNG_DURATION_INFINITE</code></a>, then no timeout is used. -If the timeout is <a href="../../api/time.html#duration-type"><code>NNG_DURATION_DEFAULT</code></a>, then a “default” or socket-specific +<a href="../api/aio.html#cancellation">aborted</a> with an error of <code>NNG_ETIMEDOUT</code>. +The <em>timeout</em> <a href="../api/time.html">duration</a> is specified as a relative number of milliseconds.</p> +<p>If the timeout is <a href="../api/time.html#duration-type"><code>NNG_DURATION_INFINITE</code></a>, then no timeout is used. +If the timeout is <a href="../api/time.html#duration-type"><code>NNG_DURATION_DEFAULT</code></a>, then a “default” or socket-specific timeout is used. -(This is frequently the same as <a href="../../api/time.html#duration-type"><code>NNG_DURATION_INFINITE</code></a>.)</p> +(This is frequently the same as <a href="../api/time.html#duration-type"><code>NNG_DURATION_INFINITE</code></a>.)</p> <p>The <a name="a013"></a><code>nng_aio_set_expire</code> function is similar to <code>nng_aio_set_timeout</code>, but sets an expiration time based on the system clock. The <em>expiration</em> -<a href="../../api/time.html">time</a> is a clock timestamp, such as would be returned by <a href="../../api/time.html#get-the-current-time"><code>nng_clock</code></a>.</p> +<a href="../api/time.html">time</a> is a clock timestamp, such as would be returned by <a href="../api/time.html#get-the-current-time"><code>nng_clock</code></a>.</p> <h2 id="wait-for-completion"><a class="header" href="#wait-for-completion">Wait for Completion</a></h2> <pre><code class="language-c">void nng_aio_wait(nng_aio *aio); </code></pre> @@ -378,7 +378,7 @@ function will not be called until the callback has completed.</p> important </p> <p>The <code>nng_aio_wait</code> function should never be called from a function that itself -is a callback of an <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, either this one or any other. +is a callback of an <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, either this one or any other. Doing so may result in a deadlock.</p> </div> <h2 id="test-for-completion"><a class="header" href="#test-for-completion">Test for Completion</a></h2> @@ -386,7 +386,7 @@ Doing so may result in a deadlock.</p> </code></pre> <p>The <a name="a015"></a><code>nng_aio_busy</code> function returns <code>true</code> if the <em>aio</em> is currently busy performing an operation or is executing a completion callback. Otherwise it return <code>false</code>. -This is the same test used internally by <a href="../../api/aio.html#wait-for-completion"><code>nng_aio_wait</code></a>.</p> +This is the same test used internally by <a href="../api/aio.html#wait-for-completion"><code>nng_aio_wait</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-important"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -402,7 +402,7 @@ size_t nng_aio_count(nng_aio *aio); <p>The <a name="a016"></a><code>nng_aio_result</code> function returns the result of the operation associated with the handle <em>aio</em>. If the operation was successful, then 0 is returned. -Otherwise a non-zero <a href="../../api/errors.html">error</a> code, such as <a href="../../api/errors.html#NNG_ECANCELED"><code>NNG_ECANCELED</code></a> or <a href="../../api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a>, is returned.</p> +Otherwise a non-zero <a href="../api/errors.html">error</a> code, such as <a href="../api/errors.html#NNG_ECANCELED"><code>NNG_ECANCELED</code></a> or <a href="../api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a>, is returned.</p> <p>For operations that transfer data, <a name="a017"></a><code>nng_aio_count</code> returns the number of bytes transferred by the operation associated with the handle <em>aio</em>. Operations that do not transfer data, or do not keep a count, may return zero for this function.</p> @@ -413,13 +413,13 @@ Operations that do not transfer data, or do not keep a count, may return zero fo </p> <p>The return value from these functions is undefined if the operation has not completed yet. Either call these from the handle’s completion callback, or after waiting for the -operation to complete with <a href="../../api/aio.html#wait-for-completion"><code>nng_aio_wait</code></a>.</p> +operation to complete with <a href="../api/aio.html#wait-for-completion"><code>nng_aio_wait</code></a>.</p> </div> <h2 id="messages"><a class="header" href="#messages">Messages</a></h2> <pre><code class="language-c">nng_msg *nng_aio_get_msg(nng_aio *aio); void nng_aio_set_msg(nng_aio *aio, nng_msg *msg); </code></pre> -<p>The <a name="a018"></a><code>nng_aio_get_msg</code> and <a name="a019"></a><code>nng_aio_set_msg</code> functions retrieve and store a <a href="../../api/msg.html">message</a> +<p>The <a name="a018"></a><code>nng_aio_get_msg</code> and <a name="a019"></a><code>nng_aio_set_msg</code> functions retrieve and store a <a href="../api/msg.html">message</a> in <em>aio</em>. For example, if a function to receive data is called, that function can generally be expected to store a message on the associated <em>aio</em>, for the application to retrieve with @@ -445,7 +445,7 @@ then no message is stored on the <em>aio</em>.</p> int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); </code></pre> -<p>For some operations, the unit of data transferred is not a <a href="../../api/msg.html">message</a>, but +<p>For some operations, the unit of data transferred is not a <a href="../api/msg.html">message</a>, but rather a stream of bytes.</p> <p>For these operations, an array of <em>niov</em> <a name="a020"></a><code>nng_iov</code> structures can be passed to the <a name="a021"></a><code>nng_aio_set_iov</code> function to provide a scatter/gather array of @@ -462,14 +462,14 @@ The values pointed to by the <code>iov_buf</code> members are <em>not</em> copie <p>Most functions using <code>nng_iov</code> do not guarantee to transfer all of the data that they are requested to. To be sure that correct amount of data is transferred, as well as to start an attempt to complete any partial transfer, check the amount of data transferred by -calling <a href="../../api/aio.html#result-of-operation"><code>nng_aio_count</code></a>.</p> +calling <a href="../api/aio.html#result-of-operation"><code>nng_aio_count</code></a>.</p> </div> <h2 id="inputs-and-outputs"><a class="header" href="#inputs-and-outputs">Inputs and Outputs</a></h2> <pre><code class="language-c">void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param); void *nng_aio_get_output(nng_aio *aio, unsigned int index); </code></pre> <p>Asynchronous operations can take additional input parameters, and -provide additional result outputs besides the <a href="../../api/aio.html#result-of-operation">result</a> code.</p> +provide additional result outputs besides the <a href="../api/aio.html#result-of-operation">result</a> code.</p> <p>The <code>nng_aio_set_input</code> function sets the input parameter at <em>index</em> to <em>param</em> for the operation associated with <em>aio</em>.</p> <p>The <code>nng_aio_get_output</code> function returns the output result at <em>index</em> @@ -505,7 +505,7 @@ in use by an active asynchronous operation.</p> 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/stream.html">streams</a>, use <a name="a023"></a>scatter or <a name="a024"></a>gather +Some asynchronous operations, such as those dealing with <a href="../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> @@ -515,13 +515,13 @@ the elements in <em>iov</em>. For each of these, the segment of size <em>iov_len 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/aio.html#result-of-operation"><code>nng_aio_count</code></a>, +successful operation should check the amount of data actually transferred using <a href="../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"><a class="header" href="#see-also">See Also</a></h2> -<p><a href="../../api/synch.html">Synchronization</a>, -<a href="../../api/thread.html">Threads</a>, -<a href="../../api/stream.html">Streams</a>, -<a href="../../api/time.html">Time</a></p> +<p><a href="../api/synch.html">Synchronization</a>, +<a href="../api/thread.html">Threads</a>, +<a href="../api/stream.html">Streams</a>, +<a href="../api/time.html">Time</a></p> <!-- NOTE: This assumes that any page referencing this is located in a directory two levels down. Meaning ./api/somefile.md or similar. mdbook cannot accommodate links that are called from diff --git a/ref/api/args.html b/ref/api/args.html index addb05b2..24a37e4a 100644 --- a/ref/api/args.html +++ b/ref/api/args.html @@ -254,7 +254,7 @@ and for this purpose a header library is supplied.</p> </p> <p>The functionality described here is entirely contained in the <code>nng/args.h</code> header file, and may be used without previously -initializing the library with <a href="../../api/init.html#initialization"><code>nng_init</code></a>, and may even be used +initializing the library with <a href="../api/init.html#initialization"><code>nng_init</code></a>, and may even be used in programs that are not linked against the NNG library.</p> </div> <h2 id="parse-command-line-arguments"><a class="header" href="#parse-command-line-arguments">Parse Command Line Arguments</a></h2> diff --git a/ref/api/ctx.html b/ref/api/ctx.html index 0aa22a6e..7130e568 100644 --- a/ref/api/ctx.html +++ b/ref/api/ctx.html @@ -246,33 +246,33 @@ <h1 id="contexts"><a class="header" href="#contexts">Contexts</a></h1> <p>Contexts <a name="a001"></a> in Scalability Protocols provide for isolation of protocol-specific state machines and associated data, allowing multiple <a name="a002"></a>concurrent <a name="a003"></a>state machines (or transactions) -to coexist on a single <a href="../../TODO.html">socket</a>.</p> -<p>For example, a <a href="../../proto/rep.html">REP</a> server may wish to allow many requests to be serviced concurrently, +to coexist on a single <a href="../TODO.html">socket</a>.</p> +<p>For example, a <a href="../proto/rep.html">REP</a> server may wish to allow many requests to be serviced concurrently, even though some jobs may take significant time to process. Contexts provide for this ability.</p> <p>Not all protocols have contexts, because many protocols simply have no state to manage. The following protocols support contexts:</p> <ul> -<li><a href="../../proto/rep.html">REP</a></li> -<li><a href="../../proto/req.html">REQ</a></li> -<li><a href="../../proto/respondent.html">RESPONDENT</a></li> -<li><a href="../../proto/surveyor.html">SURVEYOR</a></li> -<li><a href="../../proto/sub.html">SUB</a></li> +<li><a href="../proto/rep.html">REP</a></li> +<li><a href="../proto/req.html">REQ</a></li> +<li><a href="../proto/respondent.html">RESPONDENT</a></li> +<li><a href="../proto/surveyor.html">SURVEYOR</a></li> +<li><a href="../proto/sub.html">SUB</a></li> </ul> <p>For these protocols, the socket will also have a single, default, context that is used when performing send or receive operations on the socket directly.</p> <p>Other protocols are stateless, at least with respect to message processing, and have no use for -contexts. For the same reason, <a href="../../api/sock.html#raw-mode-sockets">raw</a> mode sockets do not support contexts.</p> +contexts. For the same reason, <a href="../api/sock.html#raw-mode-sockets">raw</a> mode sockets do not support contexts.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> tip </p> -<p>Developers with experience with [libnanomsg] may be used to using <a href="../../api/sock.html#raw-mode-sockets">raw</a> sockets for concurrency. +<p>Developers with experience with [libnanomsg] may be used to using <a href="../api/sock.html#raw-mode-sockets">raw</a> sockets for concurrency. Contexts provide a superior solution, as they are much easier to use, less error prone, and allow for easy control of the amount of concurrency used on any given socket.</p> </div> <p>One drawback of contexts is that they cannot be used with file descriptor polling using -<a href="../../api/sock.html#polling-socket-events"><code>nng_socket_get_recv_poll_fd</code></a> or <a href="../../api/sock.html#polling-socket-events"><code>nng_socket_get_send_poll_fd</code></a>.</p> +<a href="../api/sock.html#polling-socket-events"><code>nng_socket_get_recv_poll_fd</code></a> or <a href="../api/sock.html#polling-socket-events"><code>nng_socket_get_send_poll_fd</code></a>.</p> <h2 id="context-structure"><a class="header" href="#context-structure">Context Structure</a></h2> <pre><code class="language-c">#define NNG_CTX_INITIALIZER // opaque value @@ -285,15 +285,15 @@ to ensure that it cannot be confused with a valid open context.</p> <h2 id="creating-a-context"><a class="header" href="#creating-a-context">Creating a Context</a></h2> <pre><code class="language-c">int nng_ctx_open(nng_ctx *ctxp, nng_socket s); </code></pre> -<p>The <a name="a006"></a><code>nng_ctx_open</code> function creates a separate context to be used with the <a href="../../TODO.html">socket</a> <em>s</em>, +<p>The <a name="a006"></a><code>nng_ctx_open</code> function creates a separate context to be used with the <a href="../TODO.html">socket</a> <em>s</em>, and returns it at the location pointed by <em>ctxp</em>.</p> <h2 id="context-identity"><a class="header" href="#context-identity">Context Identity</a></h2> <pre><code class="language-c">int nng_ctx_id(nng_ctx c); </code></pre> <p>The <a name="a007"></a><code>nng_ctx_id</code> function returns a positive identifier for the context <em>c</em> if it is valid. Otherwise it returns <code>-1</code>.</p> -<p>A context is considered valid if it was ever opened with <a href="../../api/ctx.html#creating-a-context"><code>nng_ctx_open</code></a> function. -Contexts that are allocated on the stack or statically should be initialized with the macro <a href="../../api/ctx.html#context-structure"><code>NNG_CTX_INITIALIZER</code></a> +<p>A context is considered valid if it was ever opened with <a href="../api/ctx.html#creating-a-context"><code>nng_ctx_open</code></a> function. +Contexts that are allocated on the stack or statically should be initialized with the macro <a href="../api/ctx.html#context-structure"><code>NNG_CTX_INITIALIZER</code></a> to ensure that they cannot be confused with a valid context before they are opened.</p> <h2 id="closing-a-context"><a class="header" href="#closing-a-context">Closing a Context</a></h2> <pre><code class="language-c">int nng_ctx_close(nng_ctx ctx); @@ -309,7 +309,7 @@ call is executed may also return with an <code>NNG_ECLOSED</code> result.</p> <span class="mdbook-alerts-icon"></span> note </p> -<p>Closing the socket associated with <em>ctx</em> using <a href="../../api/sock.html#closing-a-socket"><code>nng_socket_close</code></a> also closes this context.</p> +<p>Closing the socket associated with <em>ctx</em> using <a href="../api/sock.html#closing-a-socket"><code>nng_socket_close</code></a> also closes this context.</p> </div> <h2 id="sending-messages"><a class="header" href="#sending-messages">Sending Messages</a></h2> <pre><code class="language-c">int nng_ctx_sendmsg(nng_ctx ctx, nng_msg *msg, int flags); @@ -325,21 +325,21 @@ messages over the socket <em>s</em>. The differences in their behaviors are as f <p>The semantics of what sending a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. Additionally, some protocols may not support sending at all or may require other pre-conditions first. -(For example, <a href="../../proto/rep.html">REP</a> sockets cannot normally send data until they have first received a request, -while <a href="../../proto/sub.html">SUB</a> sockets can only receive data and never send it.)</p> +(For example, <a href="../proto/rep.html">REP</a> sockets cannot normally send data until they have first received a request, +while <a href="../proto/sub.html">SUB</a> sockets can only receive data and never send it.)</p> </div> <h3 id="nng_ctx_sendmsg"><a class="header" href="#nng_ctx_sendmsg">nng_ctx_sendmsg</a></h3> <p>The <code>nng_ctx_sendmsg</code> function sends the <em>msg</em> over the context <em>ctx</em>.</p> <p>If this function returns zero, then the socket will dispose of <em>msg</em> when the transmission is complete. If the function returns a non-zero status, then the call retains the responsibility for disposing of <em>msg</em>.</p> -<p>The <em>flags</em> can contain the value <a href="../../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket -cannot accept more data for sending. In such a case, it will return <a href="../../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> +<p>The <em>flags</em> can contain the value <a href="../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket +cannot accept more data for sending. In such a case, it will return <a href="../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> <h3 id="nng_ctx_send"><a class="header" href="#nng_ctx_send">nng_ctx_send</a></h3> -<p>The <code>nng_ctx_send</code> function sends a message asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the context <em>ctx</em>. -The message to send must have been set on <em>aio</em> using the <a href="../../api/aio.html#messages"><code>nng_aio_set_msg</code></a> function.</p> +<p>The <code>nng_ctx_send</code> function sends a message asynchronously, using the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the context <em>ctx</em>. +The message to send must have been set on <em>aio</em> using the <a href="../api/aio.html#messages"><code>nng_aio_set_msg</code></a> function.</p> <p>If the operation completes successfully, then the context will have disposed of the message. However, if it fails, then callback of <em>aio</em> should arrange for a final disposition of the message. -(The message can be retrieved from <em>aio</em> with <a href="../../api/aio.html#messages"><code>nng_aio_get_msg</code></a>.)</p> +(The message can be retrieved from <em>aio</em> with <a href="../api/aio.html#messages"><code>nng_aio_get_msg</code></a>.)</p> <p>Note that callback associated with <em>aio</em> may be called <em>before</em> the message is finally delivered to the recipient. For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.</p> <div class="mdbook-alerts mdbook-alerts-tip"> @@ -349,7 +349,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or </p> <p>This is the preferred function to use for sending data on a context. While it does require a few extra steps on the part of the application, the lowest latencies and highest performance will be achieved by using -this function instead of <a href="../../api/ctx.html#nng_ctx_sendmsg"><code>nng_ctx_sendmsg</code></a>.</p> +this function instead of <a href="../api/ctx.html#nng_ctx_sendmsg"><code>nng_ctx_sendmsg</code></a>.</p> </div> <h2 id="receiving-messages"><a class="header" href="#receiving-messages">Receiving Messages</a></h2> <pre><code class="language-c">int nng_ctx_recvmsg(nng_ctx ctx, nng_msg **msgp, int flags); @@ -365,15 +365,15 @@ messages over the context <em>ctx</em>. The differences in their behaviors are a <p>The semantics of what receiving a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. Additionally, some protocols may not support receiving at all or may require other pre-conditions first. -(For example, <a href="../../proto/req.html">REQ</a> sockets cannot normally receive data until they have first sent a request.)</p> +(For example, <a href="../proto/req.html">REQ</a> sockets cannot normally receive data until they have first sent a request.)</p> </div> <h3 id="nng_recvmsg"><a class="header" href="#nng_recvmsg">nng_recvmsg</a></h3> -<p>The <code>nng_ctx_recvmsg</code> function receives a message and stores a pointer to the <a href="../../api/msg.html#message-structure"><code>nng_msg</code></a> for that message in <em>msgp</em>.</p> -<p>The <em>flags</em> can contain the value <a href="../../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket -has no messages available to receive. In such a case, it will return <a href="../../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> +<p>The <code>nng_ctx_recvmsg</code> function receives a message and stores a pointer to the <a href="../api/msg.html#message-structure"><code>nng_msg</code></a> for that message in <em>msgp</em>.</p> +<p>The <em>flags</em> can contain the value <a href="../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket +has no messages available to receive. In such a case, it will return <a href="../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> <h3 id="nng_socket_recv"><a class="header" href="#nng_socket_recv">nng_socket_recv</a></h3> -<p>The <code>nng_ctx_send</code> function receives a message asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the context <em>ctx</em>. -On success, the received message can be retrieved from the <em>aio</em> using the <a href="../../api/aio.html#messages"><code>nng_aio_get_msg</code></a> function.</p> +<p>The <code>nng_ctx_send</code> function receives a message asynchronously, using the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the context <em>ctx</em>. +On success, the received message can be retrieved from the <em>aio</em> using the <a href="../api/aio.html#messages"><code>nng_aio_get_msg</code></a> function.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -389,7 +389,7 @@ Failure to do so will leak the memory.</p> </p> <p>This is the preferred function to use for receiving data on a context. While it does require a few extra steps on the part of the application, the lowest latencies and highest performance will be achieved by using -this function instead of <a href="../../api/ctx.html#nng_ctx_recvmsg"><code>nng_ctx_recvmsg</code></a>.</p> +this function instead of <a href="../api/ctx.html#nng_ctx_recvmsg"><code>nng_ctx_recvmsg</code></a>.</p> </div> <h2 id="context-options"><a class="header" href="#context-options">Context Options</a></h2> <pre><code class="language-c">int nng_ctx_get_bool(nng_ctx ctx, const char *opt, bool *valp); @@ -414,7 +414,7 @@ are available for contexts, whether they can be read or written, and the appropr <p>These examples show building blocks for a concurrent service based on contexts.</p> <h3 id="example-1-context-echo-server"><a class="header" href="#example-1-context-echo-server">Example 1: Context Echo Server</a></h3> <p>The following program fragment demonstrates the use of contexts to implement -a concurrent <a href="../../proto/rep.html">REP</a> service that simply echos messages back +a concurrent <a href="../proto/rep.html">REP</a> service that simply echos messages back to the sender.</p> <pre><code class="language-c">struct echo_context { nng_ctx ctx; @@ -452,8 +452,8 @@ echo(void *arg) </code></pre> <h3 id="example-2-starting-the-echo-service"><a class="header" href="#example-2-starting-the-echo-service">Example 2: Starting the Echo Service</a></h3> <p>Given the above fragment, the following example shows setting up the service. -It assumes that the <a href="../../TODO.html">socket</a> has already been -created and any transports set up as well with functions such as <a href="../../TODO.html"><code>nng_dial</code></a> or <a href="../../TODO.html"><code>nng_listen</code></a>.</p> +It assumes that the <a href="../TODO.html">socket</a> has already been +created and any transports set up as well with functions such as <a href="../TODO.html"><code>nng_dial</code></a> or <a href="../TODO.html"><code>nng_listen</code></a>.</p> <pre><code class="language-c"> #define CONCURRENCY 1024 diff --git a/ref/api/errors.html b/ref/api/errors.html index ce682ab1..8d3c52c5 100644 --- a/ref/api/errors.html +++ b/ref/api/errors.html @@ -289,20 +289,20 @@ as in diagnostic messages or log entries.</p> <tr><td><code>NNG_EBUSY</code><a name="NNG_EBUSY"></a></td><td>4</td><td>Resource busy.</td></tr> <tr><td><code>NNG_ETIMEDOUT</code><a name="NNG_ETIMEDOUT"></a></td><td>5</td><td>Timed out. The operation took longer than the allotted time.</td></tr> <tr><td><code>NNG_ECONNREFUSED</code><a name="NNG_ECONNREFUSED"></a></td><td>6</td><td>Connection refused. Usually indicates the wrong address or a server is running.</td></tr> -<tr><td><code>NNG_ECLOSED</code><a name="NNG_ECLOSED"></a></td><td>7</td><td>Object closed. Typically the <a href="../../TODO.html">socket</a> is closed.</td></tr> +<tr><td><code>NNG_ECLOSED</code><a name="NNG_ECLOSED"></a></td><td>7</td><td>Object closed. Typically the <a href="../TODO.html">socket</a> is closed.</td></tr> <tr><td><code>NNG_EAGAIN</code><a name="NNG_EAGAIN"></a></td><td>8</td><td>Try again. Typcally for a non-blocking operation that might succeed later.</td></tr> <tr><td><code>NNG_ENOTSUP</code><a name="NNG_ENOTSUP"></a></td><td>9</td><td>Not supported. Perhaps the protocol or transport is not supported, or the operation is not not supported with the transport or protocol.</td></tr> -<tr><td><code>NNG_EADDRINUSE</code><a name="NNG_EADDRINUSE"></a></td><td>10</td><td>Address in use. The network address is already used by another process. Most often this is seen for <a href="../../TODO.html">listeners</a>.</td></tr> +<tr><td><code>NNG_EADDRINUSE</code><a name="NNG_EADDRINUSE"></a></td><td>10</td><td>Address in use. The network address is already used by another process. Most often this is seen for <a href="../TODO.html">listeners</a>.</td></tr> <tr><td><code>NNG_ESTATE</code><a name="NNG_ESTATE"></a></td><td>11</td><td>Incorrect state. The operation cannot be performed in the current state, such as trying to send a response when no request has yet been received.</td></tr> <tr><td><code>NNG_ENOENT</code><a name="NNG_ENOENT"></a></td><td>12</td><td>Entry not found (no such object.) Can also indicate that a file does not exist.</td></tr> <tr><td><code>NNG_EPROTO</code><a name="NNG_EPROTO"></a></td><td>13</td><td>Protocol error. Typically this indicates incorrect messages over a network.</td></tr> <tr><td><code>NNG_EUNREACHABLE</code><a name="NNG_EUNREACHABLE"></a></td><td>14</td><td>Destination unreachable.</td></tr> -<tr><td><code>NNG_EADDRINVAL</code><a name="NNG_EADDRINVAL"></a></td><td>15</td><td>Address invalid. Like <a href="../../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>, but only for network addresses.</td></tr> +<tr><td><code>NNG_EADDRINVAL</code><a name="NNG_EADDRINVAL"></a></td><td>15</td><td>Address invalid. Like <a href="../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>, but only for network addresses.</td></tr> <tr><td><code>NNG_EPERM</code><a name="NNG_EPERM"></a></td><td>16</td><td>Permission denied.</td></tr> <tr><td><code>NNG_EMSGSIZE</code><a name="NNG_EMSGSIZE"></a></td><td>17</td><td>Message too large.</td></tr> <tr><td><code>NNG_ECONNABORTED</code><a name="NNG_ECONNABORTED"></a></td><td>18</td><td>Connection aborted. A connection attempt was aborted locally.</td></tr> <tr><td><code>NNG_ECONNRESET</code><a name="NNG_ECONNRESET"></a></td><td>19</td><td>Connection reset. The remote peer reset the connection unexpectedly.</td></tr> -<tr><td><code>NNG_ECANCELED</code><a name="NNG_ECANCELED"></a></td><td>20</td><td>Operation canceled. Typically as a result of <a href="../../api/aio.html#cancellation"><code>nng_aio_cancel</code></a> or similar.</td></tr> +<tr><td><code>NNG_ECANCELED</code><a name="NNG_ECANCELED"></a></td><td>20</td><td>Operation canceled. Typically as a result of <a href="../api/aio.html#cancellation"><code>nng_aio_cancel</code></a> or similar.</td></tr> <tr><td><code>NNG_ENOFILES</code><a name="NNG_ENOFILES"></a></td><td>21</td><td>Out of files. Either the destination file system cannot store files, or all available file handles are used.</td></tr> <tr><td><code>NNG_ENOSPC</code><a name="NNG_ENOSPC"></a></td><td>22</td><td>Out of space. Destination table or filesystem is full.</td></tr> <tr><td><code>NNG_EEXIST</code><a name="NNG_EEXIST"></a></td><td>23</td><td>Resource already exists.</td></tr> @@ -312,7 +312,7 @@ as in diagnostic messages or log entries.</p> <tr><td><code>NNG_EPEERAUTH</code><a name="NNG_EPEERAUTH"></a></td><td>27</td><td>Peer could not be authenticated.</td></tr> <tr><td><code>NNG_EBADTYPE</code><a name="NNG_EBADTYPE"></a></td><td>30</td><td>Incorrect type. A type-specific function was used for an object of the wrong type.</td></tr> <tr><td><code>NNG_ECONNSHUT</code><a name="NNG_ECONNSHUT"></a></td><td>31</td><td>Connection shutdown. The connection was shut down and cannot be used.</td></tr> -<tr><td><code>NNG_ESTOPPED</code><a name="NNG_ESTOPPED"></a></td><td>1000</td><td>Operation stopped. The operation was stopped with <a href="../../api/aio.html#cancellation"><code>nng_aio_stop</code></a> or [<code>nng_aio_close</code>].</td></tr> +<tr><td><code>NNG_ESTOPPED</code><a name="NNG_ESTOPPED"></a></td><td>1000</td><td>Operation stopped. The operation was stopped with <a href="../api/aio.html#cancellation"><code>nng_aio_stop</code></a> or [<code>nng_aio_close</code>].</td></tr> <tr><td><code>NNG_EINTERNAL</code><a name="NNG_EINTERNAL"></a></td><td>1000</td><td>An unidentifier internal error occurred.</td></tr> <tr><td><code>NNG_ESYSERR</code><a name="NNG_ESYSERR"></a></td><td>0x10000000 - 0x1FFFFFFF</td><td>An unidentified system error occurred. These are errors reported by the operating system.</td></tr> <tr><td><code>NNG_ETRANERR</code><a name="NNG_ETRANERR"></a></td><td>0x20000000 - 0x2FFFFFFF</td><td>An unidentified transport error occurred.</td></tr> diff --git a/ref/api/http.html b/ref/api/http.html index b8db5c8c..325f793b 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -265,8 +265,8 @@ request headers, response status, response headers, and so forth.</p> performed after the first transaction is complete.</p> <p>At any given point in time, an <code>nng_http</code> object can only refer to a single HTTP transaction. In NNG, these <code>nng_http</code> objects are used in both the client and server APIs.</p> -<p>The <code>nng_http</code> object is created by either <a href="../../api/http.html#creating-connections"><code>nng_http_client_connect</code></a> or by an HTTP server -object which then passes it to an <a href="../../api/http.html#handlers"><code>nng_http_handler</code></a> callback function.</p> +<p>The <code>nng_http</code> object is created by either <a href="../api/http.html#creating-connections"><code>nng_http_client_connect</code></a> or by an HTTP server +object which then passes it to an <a href="../api/http.html#handlers"><code>nng_http_handler</code></a> callback function.</p> <h3 id="http-method"><a class="header" href="#http-method">HTTP Method</a></h3> <pre><code class="language-c">void nng_http_set_method(nng_http *conn, const char *method); const char *nng_http_get_method(nng_http *conn); @@ -285,8 +285,8 @@ const char *nng_http_get_uri(nng_http *conn); <p>The <a name="a004"></a><code>nng_http_set_uri</code> function sets the <a name="a005"></a>URI, which normally appears like a path such as “/docs/index.html”, for the next transaction on <em>conn</em>. It sets the URI to <em>uri</em>, and, if <em>query</em> is not <code>NULL</code>, also appends the contents of <em>query</em>, separated by either the ‘?’ or ‘&’ character, depending on whether <em>uri</em> already -contains a query string. It may return <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>, or <a href="../../api/errors.html#NNG_EMSGSIZE"><code>NNG_EMSGSIZE</code></a> if the the result is too long, -or <a href="../../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a> if there is some other problem with the URI.</p> +contains a query string. It may return <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>, or <a href="../api/errors.html#NNG_EMSGSIZE"><code>NNG_EMSGSIZE</code></a> if the the result is too long, +or <a href="../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a> if there is some other problem with the URI.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -304,7 +304,7 @@ const char *nng_http_get_version(nng_http *conn); <p>The <a name="a007"></a><code>nng_http_set_version</code> function is used to select the HTTP protocol version to use for the exchange. At present, only the values <code>NNG_HTTP_VERSION_1_0</code> and <code>NNG_HTTP_VERSION_1_1</code> (corresponding to “HTTP/1.0” and “HTTP/1.1”) are supported. NNG will default to using “HTTP/1.1” if this function is not called. -If an unsupported version is supplied, <a href="../../api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> will be returned, otherwise zero.</p> +If an unsupported version is supplied, <a href="../api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> will be returned, otherwise zero.</p> <p>The <a name="a008"></a><code>nng_http_get_version</code> function is used to determine the version the client selected. Normally there is little need to use this, but there are some subtle semantic differences between HTTP/1.0 and HTTP/1.1.</p> <div class="mdbook-alerts mdbook-alerts-tip"> @@ -340,7 +340,7 @@ then a built in reason based on the <em>status</em> will be used instead.</p> <span class="mdbook-alerts-icon"></span> tip </p> -<p>Callbacks used on the server may wish to use <a href="../../TODO.html"><code>nng_http_server_set_error</code></a> or <a href="../../TODO.html"><code>nng_http_server_set_redirect</code></a> instead of +<p>Callbacks used on the server may wish to use <a href="../TODO.html"><code>nng_http_server_set_error</code></a> or <a href="../TODO.html"><code>nng_http_server_set_redirect</code></a> instead of <code>nng_http_set_status</code>, because those functions will also set the response body to a suitable HTML document for display to users.</p> </div> @@ -432,11 +432,11 @@ void nng_http_del_header(nng_http *conn, const char *key); </code></pre> <p>The <a name="a015"></a><code>nng_http_add_header</code>, <a name="a016"></a><code>nng_http_set_header</code>, and <a name="a017"></a><code>nng_http_del_header</code> functions are used to add a modify either the request or response headers for <em>conn</em> prior to sending to the connected peer on <em>conn</em>.</p> -<p>Thus, if the <em>conn</em> is a client connection created by <a href="../../api/http.html#creating-connections"><code>nng_http_client_connect</code></a>, then the request headers are modified. +<p>Thus, if the <em>conn</em> is a client connection created by <a href="../api/http.html#creating-connections"><code>nng_http_client_connect</code></a>, then the request headers are modified. Conversely, if it is a connection created by an HTTP server and used in a callback function, then the response headers are modified.</p> <p>The <code>nng_http_add_header</code> function adds a header with the name <em>key</em>, and the value <em>val</em>, to the list of headers. In so doing, it may bring collapse multiple headers with the same name into a comma separated list, following -the syntax specified in RFC 9110. The function may return <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>, <a href="../../api/errors.html#NNG_EMSGSIZE"><code>NNG_EMSGSIZE</code></a>, or <a href="../../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>.</p> +the syntax specified in RFC 9110. The function may return <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>, <a href="../api/errors.html#NNG_EMSGSIZE"><code>NNG_EMSGSIZE</code></a>, or <a href="../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>.</p> <p>The <code>nng_http_set_header</code> function adds the header if it does not already exist, but replaces any and all previously existing headers with the same name <em>key</em>, if they exist. In all other respects it behaves similarly to <code>nng_http_add_header</code>.</p> <p>The <code>nng_http_del_header</code> removes all headers with name <em>key</em>.</p> @@ -495,7 +495,7 @@ including any disposing of any underlying file descriptors or related resources. </code></pre> <p>The <a name="a022"></a><code>nng_http_reset</code> function resets the request and response state of the the connection <em>conn</em>, so that it is just as if it had been freshly created with -<a href="../../api/http.html#creating-connections"><code>nng_http_client_connect</code></a> or passed into a handler function for a server callback.</p> +<a href="../api/http.html#creating-connections"><code>nng_http_client_connect</code></a> or passed into a handler function for a server callback.</p> <p>The intended purpose of this function is to clear the object state before reusing the <em>conn</em> for subsequent transactions.</p> <h3 id="direct-read-and-write"><a class="header" href="#direct-read-and-write">Direct Read and Write</a></h3> @@ -505,11 +505,11 @@ void nng_http_read_all(nng_http *conn, nng_aio *aio); void nng_http_write_all(nng_http *conn, nng_aio *aio); </code></pre> <p>The <a name="a023"></a><code>nng_http_read</code> and <a name="a024"></a><code>nng_http_write</code> functions read or write data asynchronously from or to the -connection <em>conn</em>, using the <a href="../../api/aio.html#scatter-gather-vectors"><code>nng_iov</code></a> that is set in <em>aio</em> with <a href="../../api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>. +connection <em>conn</em>, using the <a href="../api/aio.html#scatter-gather-vectors"><code>nng_iov</code></a> that is set in <em>aio</em> with <a href="../api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>. These functions will complete as soon as any data is transferred. -Use <a href="../../api/aio.html#result-of-operation"><code>nng_aio_count</code></a> to determine how much data was actually transferred.</p> +Use <a href="../api/aio.html#result-of-operation"><code>nng_aio_count</code></a> to determine how much data was actually transferred.</p> <p>The <a name="a025"></a><code>nng_http_read_all</code> and <a name="a026"></a><code>nng_http_write_all</code> functions perform the same task, but will keep resubmitting -operations until the the entire amount of data requested by the <a href="../../api/aio.html#scatter-gather-vectors"><code>nng_iov</code></a> is transferred.</p> +operations until the the entire amount of data requested by the <a href="../api/aio.html#scatter-gather-vectors"><code>nng_iov</code></a> is transferred.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -517,7 +517,7 @@ operations until the the entire amount of data requested by the <a href="../../a </p> <p>These functions perform no special handling for chunked transfers.</p> </div> -<p>These functions are most likely to be useful after hijacking the connection with <a href="../../api/http.html#hijacking-connections"><code>nng_http_hijack</code></a>. +<p>These functions are most likely to be useful after hijacking the connection with <a href="../api/http.html#hijacking-connections"><code>nng_http_hijack</code></a>. They can be used to transfer request or response body data as well.</p> <h3 id="hijacking-connections"><a class="header" href="#hijacking-connections">Hijacking Connections</a></h3> <pre><code class="language-c">nng_err nng_http_hijack(nng_http *conn); @@ -529,7 +529,7 @@ to be disassociated from the HTTP server where it was created.</p> WebSocket), where the underlying HTTP connection will be taken over for some other purpose, and should not be used any further by the server.</p> <p>This function is most useful when called from a handler function. -(See <a href="../../api/http.html#handlers"><code>nng_http_handler_alloc</code></a>.)</p> +(See <a href="../api/http.html#handlers"><code>nng_http_handler_alloc</code></a>.)</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -537,7 +537,7 @@ some other purpose, and should not be used any further by the server.</p> </p> <p>It is the responsibility of the caller to dispose of the underlying connection when it is no longer needed. Furthermore, the HTTP server will no longer send any responses to the hijacked connection, so the caller should do that as well if appropriate. -(See <a href="../../api/http.html#sending-the-response-explicitly"><code>nng_http_write_response</code></a>.)</p> +(See <a href="../api/http.html#sending-the-response-explicitly"><code>nng_http_write_response</code></a>.)</p> </div> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> @@ -554,7 +554,7 @@ Most applications will never need to use this function.</p> <p>The <a name="a028"></a><code>nng_http_peer_cert</code> function will obtain the TLS certificate object for the peer, if one is available. This can then be used for additional authentication or identity specific logic.</p> <p>The certificate must be released with [<code>nng_tls_cert_free</code>] when no longer in use. -See <a href="../../TODO.html"><code>nng_tls_cert</code></a> for more information about working with TLS certificates.</p> +See <a href="../TODO.html"><code>nng_tls_cert</code></a> for more information about working with TLS certificates.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -571,8 +571,8 @@ transactions on those connections.</p> <h3 id="client-object"><a class="header" href="#client-object">Client Object</a></h3> <pre><code class="language-c">typedef struct nng_http_client nng_http_client; </code></pre> -<p>The <a name="a029"></a><code>nng_http_client</code> object is the client side creator for <a href="../../api/http.html#connection-object"><code>nng_http</code></a> objects. -It is analogous to a <a href="../../TODO.html">dialer</a> object used elsewhere in NNG, but it specifically is only for HTTP.</p> +<p>The <a name="a029"></a><code>nng_http_client</code> object is the client side creator for <a href="../api/http.html#connection-object"><code>nng_http</code></a> objects. +It is analogous to a <a href="../TODO.html">dialer</a> object used elsewhere in NNG, but it specifically is only for HTTP.</p> <h3 id="create-a-client"><a class="header" href="#create-a-client">Create a Client</a></h3> <pre><code class="language-c">void nng_http_client_alloc(nng_http_client *clientp, const nng_url *url); </code></pre> @@ -589,7 +589,7 @@ of its resources.</p> <span class="mdbook-alerts-icon"></span> note </p> -<p>Any connections created by <a href="../../api/http.html#creating-connections"><code>nng_http_client_connect</code></a> are not affected by this function, +<p>Any connections created by <a href="../api/http.html#creating-connections"><code>nng_http_client_connect</code></a> are not affected by this function, and must be closed explicitly as needed.</p> </div> <h3 id="client-tls"><a class="header" href="#client-tls">Client TLS</a></h3> @@ -597,10 +597,10 @@ and must be closed explicitly as needed.</p> nng_err nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls); </code></pre> <p>The <a name="a032"></a><code>nng_http_client_get_tls</code> and <a name="a033"></a><code>nng_http_client_set_tls</code> functions are used to -retrieve or change the <a href="../../TODO.html">TLS configuration</a> used when making outbound connections, enabling +retrieve or change the <a href="../TODO.html">TLS configuration</a> used when making outbound connections, enabling <a name="a034"></a>TLS as a result.</p> -<p>If TLS has not been previously configured on <em>client</em>, then <code>nng_http_client_get_tls</code> will return <a href="../../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>. -Both functions will return <a href="../../api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> if either HTTP or TLS is not supported.</p> +<p>If TLS has not been previously configured on <em>client</em>, then <code>nng_http_client_get_tls</code> will return <a href="../api/errors.html#NNG_EINVAL"><code>NNG_EINVAL</code></a>. +Both functions will return <a href="../api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> if either HTTP or TLS is not supported.</p> <p>Calling <code>nng_http_client_set_tls</code> invalidates any client previously obtained with <code>nng_http_client_get_tls</code>, unless a separate hold on the object was obtained.</p> <p>Once TLS is enabled for an <code>nng_http_client</code>, it is not possible to disable TLS.</p> @@ -610,7 +610,7 @@ Both functions will return <a href="../../api/errors.html#NNG_ENOTSUP"><code>NNG note </p> <p>The TLS configuration itself cannot be changed once it has been used to create a connection, -such as by calling <a href="../../api/http.html#creating-connections"><code>nng_http_client_connect</code></a>, but a new one can be installed in the client. +such as by calling <a href="../api/http.html#creating-connections"><code>nng_http_client_connect</code></a>, but a new one can be installed in the client. Existing connections will use the TLS configuration that there were created with.</p> </div> <h3 id="creating-connections"><a class="header" href="#creating-connections">Creating Connections</a></h3> @@ -619,9 +619,9 @@ Existing connections will use the TLS configuration that there were created with void nng_http_client_connect(nng_http_client *client, nng_aio *aio); </code></pre> <p>The <a name="a035"></a><code>nng_http_client_connect</code> function makes an outgoing connection to the -server configured for <em>client</em>, and creates an <a href="../../api/http.html#connection-object"><code>nng_http</code></a> object for the connection.</p> +server configured for <em>client</em>, and creates an <a href="../api/http.html#connection-object"><code>nng_http</code></a> object for the connection.</p> <p>This is done asynchronously, and when the operation succeseds the connection may be -retried from the <em>aio</em> using <a href="../../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> with index 0.</p> +retried from the <em>aio</em> using <a href="../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> with index 0.</p> <h4 id="example-1-connecting-to-google"><a class="header" href="#example-1-connecting-to-google">Example 1: Connecting to Google</a></h4> <pre><code class="language-c">nng_aio *aio; nng_url *url; @@ -660,16 +660,16 @@ the HTTP request associated with <em>conn</em>. The entire request is sent, including headers, and if present, the request body data. (The request body can be set with -<a href="../../api/http.html#storing-body-content"><code>nng_http_set_body</code></a> or <a href="../../api/http.html#storing-body-content"><code>nng_http_copy_body</code></a>.)</p> +<a href="../api/http.html#storing-body-content"><code>nng_http_set_body</code></a> or <a href="../api/http.html#storing-body-content"><code>nng_http_copy_body</code></a>.)</p> <p>This function returns 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/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p> +may be obtained via <a href="../api/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> tip </p> -<p>Consider using the <a href="../../api/http.html#submitting-the-transaction"><code>nng_http_transact</code></a> function, +<p>Consider using the <a href="../api/http.html#submitting-the-transaction"><code>nng_http_transact</code></a> function, which provides a simpler interface for performing a complete HTTP client transaction.</p> </div> <h3 id="obtaining-the-response"><a class="header" href="#obtaining-the-response">Obtaining the Response</a></h3> @@ -678,7 +678,7 @@ which provides a simpler interface for performing a complete HTTP client transac <p>The <a name="a037"></a><code>nng_http_read_response</code> function starts an asynchronous read from the HTTP connection <em>conn</em>, reading an HTTP response into the response associated with <em>conn</em>, including all of the related headers.</p> -<p>It does <em>not</em> transfer any response body. To do that, use <a href="../../api/http.html#direct-read-and-write"><code>nng_http_read_all</code></a> or <a href="../../api/http.html#direct-read-and-write"><code>nng_http_read</code></a>.</p> +<p>It does <em>not</em> transfer any response body. To do that, use <a href="../api/http.html#direct-read-and-write"><code>nng_http_read_all</code></a> or <a href="../api/http.html#direct-read-and-write"><code>nng_http_read</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -692,7 +692,7 @@ need to do so may use the direct read functions.</p> <span class="mdbook-alerts-icon"></span> tip </p> -<p>An easier one-shot method for many use cases might be <a href="../../api/http.html#submitting-the-transaction"><code>nng_http_transact</code></a>.</p> +<p>An easier one-shot method for many use cases might be <a href="../api/http.html#submitting-the-transaction"><code>nng_http_transact</code></a>.</p> </div> <h3 id="submitting-the-transaction"><a class="header" href="#submitting-the-transaction">Submitting the Transaction</a></h3> <pre><code class="language-c">void nng_http_transact(nng_http *conn, nng_aio *aio); @@ -703,11 +703,11 @@ When the function is complete, the <em>aio</em> will be notified.</p> HTTP exchange over the connection <em>conn</em>, sending the request and attached body data to the remote server, and reading the response.</p> <p>The entire response is read, including any associated body, which can -subsequently be obtained using <a href="../../api/http.html#retrieving-body-content"><code>nng_http_get_body</code></a>.</p> +subsequently be obtained using <a href="../api/http.html#retrieving-body-content"><code>nng_http_get_body</code></a>.</p> <p>This function is intended to make creation of client applications easier, by performing multiple asynchronous operations required to complete an entire HTTP transaction.</p> -<p>If an error occurs, the caller should close <em>conn</em> with <a href="../../api/http.html#closing-the-connection"><code>nng_http_close</code></a>, as it may not +<p>If an error occurs, the caller should close <em>conn</em> with <a href="../api/http.html#closing-the-connection"><code>nng_http_close</code></a>, as it may not necessarily be usable with other transactions.</p> <div class="mdbook-alerts mdbook-alerts-warning"> <p class="mdbook-alerts-title"> @@ -731,7 +731,7 @@ request interleaving.</p> </div> <p>This function returns 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/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p> +may be obtained via <a href="../api/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p> <h3 id="response-body"><a class="header" href="#response-body">Response Body</a></h3> <h2 id="server-api"><a class="header" href="#server-api">Server API</a></h2> <h3 id="handlers"><a class="header" href="#handlers">Handlers</a></h3> @@ -745,7 +745,7 @@ Only the path component of the Request URI is considered when determining whethe <p>This implementation limits the <em>path</em> length to 1024 bytes, including the zero termination byte. This does not prevent requests with much longer URIs from being supported, but doing so will require setting the handler to match a parent path in the tree using -<a href="../../api/http.html#handling-an-entire-tree"><code>nng_http_handler_set_tree</code></a>.</p> +<a href="../api/http.html#handling-an-entire-tree"><code>nng_http_handler_set_tree</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -754,11 +754,11 @@ URIs from being supported, but doing so will require setting the handler to matc <p>The NNG HTTP framework is optimized for URLs shorter than 200 characters.</p> </div> <p>Additionally each handler has a method it is registered to handle -(the default is “GET” andc can be changed with <a href="../../api/http.html#setting-the-method"><code>nng_http_handler_set_method</code></a>), and -optionally a “Host” header it can be matched against (see <a href="../../api/http.html#filtering-byt-host"><code>nng_http_handler_set_host</code></a>).</p> +(the default is “GET” andc can be changed with <a href="../api/http.html#setting-the-method"><code>nng_http_handler_set_method</code></a>), and +optionally a “Host” header it can be matched against (see <a href="../api/http.html#filtering-byt-host"><code>nng_http_handler_set_host</code></a>).</p> <p>In some cases, a handler may reference a logical tree rather (directory) rather than just a single element. -(See <a href="../../api/http.html#handling-an-entire-tree"><code>nng_http_handler_set_tree</code></a>).</p> +(See <a href="../api/http.html#handling-an-entire-tree"><code>nng_http_handler_set_tree</code></a>).</p> <h3 id="implementing-a-handler"><a class="header" href="#implementing-a-handler">Implementing a Handler</a></h3> <pre><code class="language-c">typedef void (*nng_http_handler_func)(nng_http_conn *conn, void *arg, nng_aio *aio); @@ -770,30 +770,30 @@ On success, a pointer to the handler is stored at the located pointed to by <em> <p>The handler function is specified by <em>cb</em>. This function uses the asynchronous I/O framework.</p> <p>The function receives the connection on <em>conn</em>, and an optional data pointer that was set -previously with <a href="../../api/http.html#setting-the-callback-argument"><code>nng_http_handler_set_data</code></a> as the second argument. The -final argument is the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, which must be “finished” to complete the operation.</p> -<p>The handler may call <a href="../../api/http.html#sending-the-response-explicitly"><code>nng_http_write_response</code></a> to send the response, or +previously with <a href="../api/http.html#setting-the-callback-argument"><code>nng_http_handler_set_data</code></a> as the second argument. The +final argument is the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, which must be “finished” to complete the operation.</p> +<p>The handler may call <a href="../api/http.html#sending-the-response-explicitly"><code>nng_http_write_response</code></a> to send the response, or it may simply let the framework do so on its behalf. The server will perform this step if the callback has not already done so.</p> -<p>Response headers may be set using <a href="../../api/http.html#modifying-headers"><code>nng_http_set_header</code></a>, and request headers -may be accessed by using <a href="../../api/http.html#retrieving-headers"><code>nng_http_get_header</code></a>. They can also be iterated -over using <a href="../../api/http.html#retrieving-headers"><code>nng_http_next_header</code></a></p> -<p>Likewise the request body may be accessed, using <a href="../../api/http.html#retrieving-body-content"><code>nng_http_get_body</code></a>, and -the response body may be set using either <a href="../../api/http.html#storing-body-content"><code>nng_http_set_body</code></a> or <a href="../../api/http.html#storing-body-content"><code>nng_http_copy_body</code></a>.</p> +<p>Response headers may be set using <a href="../api/http.html#modifying-headers"><code>nng_http_set_header</code></a>, and request headers +may be accessed by using <a href="../api/http.html#retrieving-headers"><code>nng_http_get_header</code></a>. They can also be iterated +over using <a href="../api/http.html#retrieving-headers"><code>nng_http_next_header</code></a></p> +<p>Likewise the request body may be accessed, using <a href="../api/http.html#retrieving-body-content"><code>nng_http_get_body</code></a>, and +the response body may be set using either <a href="../api/http.html#storing-body-content"><code>nng_http_set_body</code></a> or <a href="../api/http.html#storing-body-content"><code>nng_http_copy_body</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> note </p> <p>The request body is only collected for the handler if the -<a href="../../api/http.html#collecting-request-body"><code>nng_http_handler_collect_body</code></a> function has been called for the handler.</p> +<a href="../api/http.html#collecting-request-body"><code>nng_http_handler_collect_body</code></a> function has been called for the handler.</p> </div> -<p>The HTTP status should be set for the transaction using <a href="../../api/http.html#http-status"><code>nng_http_set_status</code></a>.</p> -<p>Finally, the handler should finish the operation by calling the <a href="../../TODO.html"><code>nng_aio_finish</code></a> function -after having set the status to <a href="../../api/errors.html#NNG_OK"><code>NNG_OK</code></a>. +<p>The HTTP status should be set for the transaction using <a href="../api/http.html#http-status"><code>nng_http_set_status</code></a>.</p> +<p>Finally, the handler should finish the operation by calling the <a href="../TODO.html"><code>nng_aio_finish</code></a> function +after having set the status to <a href="../api/errors.html#NNG_OK"><code>NNG_OK</code></a>. If any other status is set on the <em>aio</em>, then a generic 500 response will be created and sent, if possible, and the connection will be closed.</p> -<p>The <em>aio</em> may be scheduled for deferred completion using the <a href="../../TODO.html"><code>nng_aio_start</code></a>.</p> +<p>The <em>aio</em> may be scheduled for deferred completion using the <a href="../TODO.html"><code>nng_aio_start</code></a>.</p> <h3 id="serving-directories-and-files"><a class="header" href="#serving-directories-and-files">Serving Directories and Files</a></h3> <pre><code class="language-c">nng_err nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, const char *dirname); nng_err nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, const char *filename); @@ -819,7 +819,7 @@ then a value of <code>application/octet-stream</code> is assumed.</p> </code></pre> <p>The <a name="a045"></a><code>nng_http_handler_alloc_redirect</code> function creates a handler with a function that simply directions from the URI at <em>path</em> to the given <em>location</em>.</p> -<p>The HTTP reply it creates will be with <a href="../../api/http.html#http-status">status code</a> <em>status</em>, +<p>The HTTP reply it creates will be with <a href="../api/http.html#http-status">status code</a> <em>status</em>, which should be a 3XX code such as 301, and a <code>Location:</code> header will contain the URL referenced by <em>location</em>, with any residual suffix from the request URI appended.</p> @@ -828,7 +828,7 @@ URI appended.</p> <span class="mdbook-alerts-icon"></span> tip </p> -<p>Use <a href="../../api/http.html#handling-an-entire-tree"><code>nng_http_handler_set_tree</code></a> to redirect an entire tree. +<p>Use <a href="../api/http.html#handling-an-entire-tree"><code>nng_http_handler_set_tree</code></a> to redirect an entire tree. For example, it is possible to redirect an entire HTTP site to another HTTPS site by specifying <code>/</code> as the path and then using the base of the new site, such as <code>https://newsite.example.com</code> as the new location.</p> @@ -839,10 +839,10 @@ of the new site, such as <code>https://newsite.example.com</code> as the new loc tip </p> <p>Be sure to use the appropriate value for <em>status</em>. -Permanent redirection should use <a href="../../api/http.html#NNG_HTTP_STATUS_MOVED_PERMANENTLY"><code>NNG_HTTP_STATUS_MOVED_PERMANENTLY</code></a> (301) -and temporary redirections should use <a href="../../api/http.html#NNG_HTTP_STATUS_TEMPORARY_REDIRECT"><code>NNG_HTTP_STATUS_TEMPORARY_REDIRECT</code></a> (307). +Permanent redirection should use <a href="../api/http.html#NNG_HTTP_STATUS_MOVED_PERMANENTLY"><code>NNG_HTTP_STATUS_MOVED_PERMANENTLY</code></a> (301) +and temporary redirections should use <a href="../api/http.html#NNG_HTTP_STATUS_TEMPORARY_REDIRECT"><code>NNG_HTTP_STATUS_TEMPORARY_REDIRECT</code></a> (307). In REST APIs, using a redirection to supply the new location of an object -created with <code>POST</code> should use <a href="../../api/http.html#NNG_HTTP_STATUS_SEE_OTHER"><code>NNG_HTTP_STATUS_SEE_OTHER</code></a> (303).</p> +created with <code>POST</code> should use <a href="../api/http.html#NNG_HTTP_STATUS_SEE_OTHER"><code>NNG_HTTP_STATUS_SEE_OTHER</code></a> (303).</p> </div> <h3 id="collecting-request-body"><a class="header" href="#collecting-request-body">Collecting Request Body</a></h3> <pre><code class="language-c">void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz); @@ -851,12 +851,12 @@ created with <code>POST</code> should use <a href="../../api/http.html#NNG_HTTP_ framework collect any request body for the request and attach it to the connection before calling the callback for the <em>handler</em>.</p> <p>Subsequently the data can be retrieved by the handler from the request with the -<a href="../../api/http.html#retrieving-body-content"><code>nng_http_get_body</code></a> function.</p> +<a href="../api/http.html#retrieving-body-content"><code>nng_http_get_body</code></a> function.</p> <p>The collection is enabled if <em>want</em> is true. Furthermore, the data that the client may sent is limited by the value of <em>maxsz</em>. If the client attempts to send more data than <em>maxsz</em>, then the -request will be terminated with <a href="../../api/http.html#NNG_HTTP_STATUS_CONTENT_TOO_LARGE"><code>NNG_HTTP_STATUS_CONTENT_TOO_LARGE</code></a> (413).</p> +request will be terminated with <a href="../api/http.html#NNG_HTTP_STATUS_CONTENT_TOO_LARGE"><code>NNG_HTTP_STATUS_CONTENT_TOO_LARGE</code></a> (413).</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -903,7 +903,7 @@ The intended use of this function is deallocate any resources associated with <e <em>handler</em> will be called for, such as “GET” or “POST”. (By default the “GET” method is handled.)</p> <p>If <em>method</em> is <code>NULL</code> the handler will be executed for all methods. -The handler may determine the actual method used with the <a href="../../api/http.html#http-method"><code>nng_http_get_method</code></a> function.</p> +The handler may determine the actual method used with the <a href="../api/http.html#http-method"><code>nng_http_get_method</code></a> function.</p> <p>The server will automatically call “GET” handlers if the client sends a “HEAD” request, and will suppress HTTP body data in the responses sent for such requests.</p> @@ -954,9 +954,9 @@ It can also provide a logical fallback instead of relying on a 404 error code.</ <pre><code class="language-c">void nng_http_write_response(nng_http *conn, nng_aio *aio); </code></pre> <p>Normally the server will send any attached response, but there are circumstances where -a response must be sent manually, such as when <a href="../../api/http.html#hijacking-connections">hijacking</a> a connection.</p> +a response must be sent manually, such as when <a href="../api/http.html#hijacking-connections">hijacking</a> a connection.</p> <p>In such a case, <a name="a051"></a><code>nng_http_write_response</code> can be called, which will send the response and any attached data, asynchronously -using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>.</p> +using the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>.</p> <p>By default, for <code>HTTP/1.1</code> connections, the connection is kept open, and will be reused to receive new requests. For <code>HTTP/1.0</code>, or if the client has requested explicitly by setting the “Connection: close” header, the connection will be closed after the diff --git a/ref/api/id_map.html b/ref/api/id_map.html index efa7d2ae..ddb8030d 100644 --- a/ref/api/id_map.html +++ b/ref/api/id_map.html @@ -267,7 +267,7 @@ will use space efficiently even if identifiers are very far apart. important </p> <p>The function available for <code>nng_id_map</code> are <em>not</em> thread-safe. -Callers should use a <a href="../../api/synch.html#mutual-exclusion-lock">mutex</a> or similar approach when thread-safety is needed.</p> +Callers should use a <a href="../api/synch.html#mutual-exclusion-lock">mutex</a> or similar approach when thread-safety is needed.</p> </div> <h2 id="create-id-map"><a class="header" href="#create-id-map">Create ID Map</a></h2> <pre><code class="language-c">#define NNG_MAP_RANDOM 1 @@ -285,7 +285,7 @@ This is useful to reduce the odds of different instances of an application using the same identifiers at the same time.</p> <p>If both <em>lo</em> and <em>hi</em> are zero, then the values <code>0</code> and <code>0xffffffff</code> are substituted in their place, giving a full range of 32-bit identifiers.</p> -<p>This function can return <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if it is unable to allocate resources, otherwise +<p>This function can return <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if it is unable to allocate resources, otherwise it returns zero on success.</p> <h2 id="destroy-map"><a class="header" href="#destroy-map">Destroy Map</a></h2> <pre><code class="language-c">void nng_id_map_free(nng_id_map *map); @@ -315,7 +315,7 @@ index <em>id</em>.</p> <p>The <em>value</em> must not be <code>NULL</code>.</p> </div> <p>If the table has to grow to accommodate this value, it may fail if insufficient -memory is available, returning <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>. Otherwise it returns zero.</p> +memory is available, returning <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>. Otherwise it returns zero.</p> <h2 id="lookup-a-value"><a class="header" href="#lookup-a-value">Lookup a Value</a></h2> <pre><code class="language-c">void *nng_id_get(nng_id_map *map, uint64_t id); </code></pre> @@ -331,16 +331,16 @@ largest possible identifier is allocated. After wrapping, only identifiers that in use will be considered. No effort is made to order the availability of identifiers based on when they were freed.<sup><a name="to-footnote-2"><a href="#footnote-2">2</a></a></sup></p> -<p>As with <a href="../../api/id_map.html#store-a-value"><code>nng_id_set</code></a>, this may need to allocate memory and can thus -fail with <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p> +<p>As with <a href="../api/id_map.html#store-a-value"><code>nng_id_set</code></a>, this may need to allocate memory and can thus +fail with <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p> <p>Additionally, if there are no more free identifiers within the range specified -when <em>map</em> was created, then it will return <a href="../../api/errors.html#NNG_ENOSPC"><code>NNG_ENOSPC</code></a>.</p> +when <em>map</em> was created, then it will return <a href="../api/errors.html#NNG_ENOSPC"><code>NNG_ENOSPC</code></a>.</p> <p>Otherwise it returns zero, indicating success.</p> <h2 id="remove-an-id"><a class="header" href="#remove-an-id">Remove an ID</a></h2> <pre><code class="language-c">int nng_id_remove(nng_id_map *map, uint64_t id); </code></pre> <p>The <a name="a007"></a><code>nng_id_remove</code> removes the entry at index <em>id</em> from <em>map</em>.</p> -<p>If no such entry exist, it will return <a href="../../api/errors.html#NNG_ENOENT"><code>NNG_ENOENT</code></a>. Otherwise it returns zero.</p> +<p>If no such entry exist, it will return <a href="../api/errors.html#NNG_ENOENT"><code>NNG_ENOENT</code></a>. Otherwise it returns zero.</p> <h2 id="iterating-ids"><a class="header" href="#iterating-ids">Iterating IDs</a></h2> <pre><code class="language-c">bool nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor); </code></pre> diff --git a/ref/api/init.html b/ref/api/init.html index 777d95fb..0fe04827 100644 --- a/ref/api/init.html +++ b/ref/api/init.html @@ -263,12 +263,12 @@ extern nng_err nng_init(nng_init_params *params); <p>Before using other interfaces in this library, it is necessary to initialize the library. The <a name="a001"></a><code>nng_init</code> function performs this initialization.</p> <p>The function is idempotent, although on tear down, every call to <code>nng_init</code> must -be paired with a call to <a href="../../api/init.html#finalization"><code>nng_fini</code></a> or no resources will be released. +be paired with a call to <a href="../api/init.html#finalization"><code>nng_fini</code></a> or no resources will be released. This allows for libraries consuming these interfaces to safely initialize and finalize the library without disrupting other consumers in the same process.</p> <p>Further, only the first call to this function may have a value of <em>params</em> other than <code>NULL</code>. If <em>params</em> is not <code>NULL</code>, and the library has already been intiazed, then <code>nng_init</code> will -return <a href="../../api/errors.html#NNG_EBUSY"><code>NNG_EBUSY</code></a>.</p> +return <a href="../api/errors.html#NNG_EBUSY"><code>NNG_EBUSY</code></a>.</p> <p>In some cases it is desirable to tune certain runtime parameters for the library, which can be done by supplying a non-<code>NULL</code> <em>params</em> argument.</p> <h3 id="parameters"><a class="header" href="#parameters">Parameters</a></h3> @@ -312,7 +312,7 @@ Changes the number of threads used for asynchronous DNS look ups.</p> </code></pre> <p>When the consumer is ready to deallocate any resources allocated by the library, it should call the <a name="a002"></a><code>nng_fini</code> function. Each call to <code>nng_fini</code> should be paired with an earlier call to -<a href="../../api/init.html#initialization"><code>nng_init</code></a>.</p> +<a href="../api/init.html#initialization"><code>nng_init</code></a>.</p> <p>After calling <code>nng_fini</code>, the consuming application must not make any other calls to NNG functions, except that it may use <code>nng_init</code> to initialize the application for further use.</p> <!-- NOTE: This assumes that any page referencing this is located diff --git a/ref/api/memory.html b/ref/api/memory.html index 949c81ce..47f41bcc 100644 --- a/ref/api/memory.html +++ b/ref/api/memory.html @@ -256,8 +256,8 @@ at least <em>size</em> bytes, and returns a pointer to it. The memory will be 64-bit aligned. Note that the memory may have random data in it, just like with <code>malloc</code>.</p> <p>If memory cannot be allocated for any reason, then <code>NULL</code> will be returned. -Applications that experience this should treat this like <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p> -<p>Memory returned by <code>nng_alloc</code> should be freed when no longer needed using <a href="../../api/memory.html#deallocate-memory"><code>nng_free</code></a>.</p> +Applications that experience this should treat this like <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>.</p> +<p>Memory returned by <code>nng_alloc</code> should be freed when no longer needed using <a href="../api/memory.html#deallocate-memory"><code>nng_free</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-important"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -270,26 +270,26 @@ other unpredictable behavior.</p> <h2 id="deallocate-memory"><a class="header" href="#deallocate-memory">Deallocate Memory</a></h2> <pre><code class="language-c">void nng_free(void *ptr, size_t size); </code></pre> -<p>The <a name="a004"></a><code>nng_free</code> function deallocates memory previously allocated by <a href="../../api/memory.html#allocate-memory"><code>nng_alloc</code></a>.</p> +<p>The <a name="a004"></a><code>nng_free</code> function deallocates memory previously allocated by <a href="../api/memory.html#allocate-memory"><code>nng_alloc</code></a>.</p> <p>The <em>size</em> argument must exactly match the <em>size</em> argument that was supplied to -<a href="../../api/memory.html#allocate-memory"><code>nng_alloc</code></a> when the memory was allocated.</p> +<a href="../api/memory.html#allocate-memory"><code>nng_alloc</code></a> when the memory was allocated.</p> <h2 id="duplicate-string"><a class="header" href="#duplicate-string">Duplicate String</a></h2> <pre><code class="language-c">char *nng_strdup(const char *src); </code></pre> <p>The <a name="a005"></a><code>nng_strdup</code> duplicates the string <em>src</em> and returns it.</p> -<p>This is logically equivalent to using <a href="../../api/memory.html#allocate-memory"><code>nng_alloc</code></a> +<p>This is logically equivalent to using <a href="../api/memory.html#allocate-memory"><code>nng_alloc</code></a> to allocate a region of memory of <code>strlen(s) + 1</code> bytes, and then using <code>strcpy</code> to copy the string into the destination before returning it.</p> <p>The returned string should be deallocated with -<a href="../../api/memory.html#free-string"><code>nng_strfree</code></a>, or may be deallocated using the -<a href="../../api/memory.html#deallocate-memory"><code>nng_free</code></a> using the length of the returned string plus +<a href="../api/memory.html#free-string"><code>nng_strfree</code></a>, or may be deallocated using the +<a href="../api/memory.html#deallocate-memory"><code>nng_free</code></a> using the length of the returned string plus one (for the <code>NUL</code> terminating byte).</p> <h2 id="free-string"><a class="header" href="#free-string">Free String</a></h2> <pre><code class="language-c">void nng_strfree(char *str); </code></pre> <p>The <a name="a006"></a><code>nng_strfree</code> function is a convenience function that -can be used to deallocate strings allocated with <a href="../../api/memory.html#duplicate-string"><code>nng_strdup</code></a>.</p> +can be used to deallocate strings allocated with <a href="../api/memory.html#duplicate-string"><code>nng_strdup</code></a>.</p> <p>It is effectively the same as <code>nng_free(strlen(str) + 1)</code>.</p> <!-- NOTE: This assumes that any page referencing this is located in a directory two levels down. Meaning ./api/somefile.md or diff --git a/ref/api/misc.html b/ref/api/misc.html index 21e678e7..6dbaf8b2 100644 --- a/ref/api/misc.html +++ b/ref/api/misc.html @@ -258,7 +258,7 @@ number facilities when available.</p> </code></pre> <p>The <a name="a003"></a><code>nng_socket_pair</code> function creates a pair of connected file descriptors. These file descriptors, which are returned in the <em>fds</em> array, are suitable for -use with the <a href="../../tran/socket.html">Socket transport</a>.</p> +use with the <a href="../tran/socket.html">Socket transport</a>.</p> <p>On POSIX platforms, this is a thin wrapper around the standard <code>socketpair</code> function, using the <a name="a004"></a><code>AF_UNIX</code> family and the <code>SOCK_STREAM</code> socket type. <sup><a name="to-footnote-1"><a href="#footnote-1">1</a></a></sup></p> diff --git a/ref/api/msg.html b/ref/api/msg.html index 28e23337..b2c19276 100644 --- a/ref/api/msg.html +++ b/ref/api/msg.html @@ -246,15 +246,15 @@ <h1 id="messages"><a class="header" href="#messages">Messages</a></h1> <p>Messages <a name="a001"></a> in Scalability Protocols are the fundamental unit of transmission and reception, as these protocols are fundamentally message-oriented.</p> -<p>Messages have a <a href="../../api/msg.html#message-body">body</a><a name="a002"></a>, containing the application-supplied -payload, and a <a href="../../api/msg.html#message-header">header</a><a name="a003"></a>, containing protocol specific routing and similar +<p>Messages have a <a href="../api/msg.html#message-body">body</a><a name="a002"></a>, containing the application-supplied +payload, and a <a href="../api/msg.html#message-header">header</a><a name="a003"></a>, containing protocol specific routing and similar related information.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> tip </p> -<p>Only applications using <a href="../../api/sock.html#raw-mode-sockets">raw mode</a> need to access the message header. +<p>Only applications using <a href="../api/sock.html#raw-mode-sockets">raw mode</a> need to access the message header. Very few <em>NNG</em> applications do this.</p> </div> <h2 id="message-structure"><a class="header" href="#message-structure">Message Structure</a></h2> @@ -268,7 +268,7 @@ and a header.</p> <p>The <a name="a005"></a><code>nng_msg_alloc</code> function allocates a new message. It takes a <em>size</em> argument, and returns a message with a preallocated body of that size in the <em>msgp</em> parameter.</p> -<p>If it succeeds, it returns zero, otherwise this function may return <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>, +<p>If it succeeds, it returns zero, otherwise this function may return <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>, indicating that insufficient memory is available to allocate a new message.</p> <h3 id="destroy-a-message"><a class="header" href="#destroy-a-message">Destroy a Message</a></h3> <pre><code class="language-c">void nng_msg_free(nng_msg *msg); @@ -278,7 +278,7 @@ indicating that insufficient memory is available to allocate a new message.</p> <pre><code class="language-c">int nng_msg_dup(nng_msg **dup, nng_msg *msg); </code></pre> <p>The <a name="a007"></a><code>nng_msg_dup</code> function duplicates the message <em>msg</em>, storing a pointer -to the new duplicate in <em>dup</em>. This function also returns zero on success, or <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> +to the new duplicate in <em>dup</em>. This function also returns zero on success, or <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if memory is exhausted.</p> <h2 id="message-size-and-capacity"><a class="header" href="#message-size-and-capacity">Message Size and Capacity</a></h2> <pre><code class="language-c">size_t nng_msg_capacity(nng_msg *msg); @@ -311,7 +311,7 @@ If reallocation fails due to insufficient memory, then the original is left inta is at least <em>capacity</em> bytes. Use of this function to ensure the total anticipated capacity is present in the message may help prevent many small allocations.</p> <p>Both <code>nng_msg_realloc</code> and <code>nng_msg_reserve</code> return zero on success, or may return -<a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if insufficient memory exists to preform allocation.</p> +<a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if insufficient memory exists to preform allocation.</p> <div class="mdbook-alerts mdbook-alerts-important"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -418,7 +418,7 @@ int nng_msg_header_insert_u64(nng_msg *msg, uint64_t val64); </code></pre> <p>Appending data to a message header is done by using the <a name="a021"></a><code>nng_msg_header_append</code> functions, and inserting data in the header is done using the <a name="a022"></a><code>nng_msg_header_insert</code> functions.</p> -<p>These functions act just like the <a href="../../api/msg.html#add-to-body"><code>nng_msg_append</code></a> and <a href="../../api/msg.html#add-to-body"><code>nng_msg_insert</code></a> functions, +<p>These functions act just like the <a href="../api/msg.html#add-to-body"><code>nng_msg_append</code></a> and <a href="../api/msg.html#add-to-body"><code>nng_msg_insert</code></a> functions, except that they operate on the message header rather than the message body.</p> <h3 id="consume-from-header"><a class="header" href="#consume-from-header">Consume from Header</a></h3> <pre><code class="language-c">int nng_msg_header_chop(nng_msg *msg, size_t size); @@ -433,16 +433,16 @@ int nng_msg_header_trim_u64(nng_msg *msg, uint64_t *val64); </code></pre> <p>The <a name="a023"></a><code>nng_msg_header_trim</code> functions remove data from the beginning of the message header, and the <a name="a024"></a><code>nng_msg_header_chop</code> functions remove data from the end of the message header.</p> -<p>These functions act just like the <a href="../../api/msg.html#consume-from-body"><code>nng_msg_trim</code></a> and <a href="../../api/msg.html#consume-from-body"><code>nng_msg_chop</code></a> functions, +<p>These functions act just like the <a href="../api/msg.html#consume-from-body"><code>nng_msg_trim</code></a> and <a href="../api/msg.html#consume-from-body"><code>nng_msg_chop</code></a> functions, except that they operate the message header rather than the message body.</p> <h2 id="message-pipe"><a class="header" href="#message-pipe">Message Pipe</a></h2> <pre><code class="language-c">nng_pipe nng_msg_get_pipe(nng_msg *msg); void nng_msg_get_pipe(nng_msg *msg, nng_pipe p); </code></pre> -<p>The <a name="a025"></a><code>nng_msg_set_pipe</code> function sets the <a href="../../api/pipe.html">pipe</a> associated with <em>msg</em> to <em>p</em>. +<p>The <a name="a025"></a><code>nng_msg_set_pipe</code> function sets the <a href="../api/pipe.html">pipe</a> associated with <em>msg</em> to <em>p</em>. This is most often useful when used with protocols that support directing a message to a specific peer. -For example the <a href="../../proto/pair.html"><em>PAIR</em></a> version 1 protocol can do +For example the <a href="../proto/pair.html"><em>PAIR</em></a> version 1 protocol can do this when <code>NNG_OPT_PAIR1_POLY</code> mode is set.</p> <p>The <a name="a026"></a><code>nng_msg_get_pipe</code> function returns the pipe that was previously set on the message <em>m</em>, either directly by the application, or when the message was received by the protocol.</p> diff --git a/ref/api/pipe.html b/ref/api/pipe.html index 49d703ce..b70e4a11 100644 --- a/ref/api/pipe.html +++ b/ref/api/pipe.html @@ -269,7 +269,7 @@ accurate type checks in functions passing values of this type.</p> However it is possible to access a pipe when more information about the source of a message is needed, or when more control is required over message delivery.</p> </div> -<p>Pipe objects are created by <a href="../../TODO.html">dialers</a> and and <a href="../../TODO.html">listeners</a>.</p> +<p>Pipe objects are created by <a href="../TODO.html">dialers</a> and and <a href="../TODO.html">listeners</a>.</p> <h2 id="initialization"><a class="header" href="#initialization">Initialization</a></h2> <p>A pipe may be initialized using the macro <a name="a004"></a><code>NNG_PIPE_INITIALIZER</code> before it is opened, to prevent confusion with valid open pipes.</p> @@ -288,7 +288,7 @@ Otherwise it returns <code>-1</code>.</p> </p> <p>A pipe is considered valid if it was ever created by the socket. Pipes that are allocated on the stack or statically should be initialized with the macro -<a href="../../api/pipe.html#initialization"><code>NNG_PIPE_INITIALIZER</code></a> to ensure that they cannot be confused with a valid pipe.</p> +<a href="../api/pipe.html#initialization"><code>NNG_PIPE_INITIALIZER</code></a> to ensure that they cannot be confused with a valid pipe.</p> </div> <h2 id="closing-a-pipe"><a class="header" href="#closing-a-pipe">Closing a Pipe</a></h2> <pre><code class="language-c">nng_err nng_pipe_close(nng_pipe p); @@ -296,7 +296,7 @@ Pipes that are allocated on the stack or statically should be initialized with t <p>The <a name="a006"></a><code>nng_pipe_close</code> function closes the supplied pipe, <em>p</em>. Messages that have been submitted for sending may be flushed or delivered, depending upon the transport.</p> -<p>Further attempts to use the pipe after this call returns will result in <a href="../../api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.</p> +<p>Further attempts to use the pipe after this call returns will result in <a href="../api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -313,7 +313,7 @@ nng_socket nng_pipe_socket(nng_pipe p); <p><a name="a007"></a> <a name="a008"></a> <a name="a009"></a> -These functions return the <a href="../../TODO.html">socket</a>, <a href="../../TODO.html">dialer</a>, or <a href="../../TODO.html">listener</a> that created or owns the pipe.</p> +These functions return the <a href="../TODO.html">socket</a>, <a href="../TODO.html">dialer</a>, or <a href="../TODO.html">listener</a> that created or owns the pipe.</p> <p>If the pipe was does not have an associated dialer or listener, then the associated will return [<code>NNG_DIALER_INITIALIZER</code>] or [<code>NNG_LISTENER_INITIALIZER</code>], as appropriate, and either [<code>nng_dialer_id</code>] or [<code>nng_listener_id</code>] for the returned object will return -1.</p> @@ -323,7 +323,7 @@ either [<code>nng_dialer_id</code>] or [<code>nng_listener_id</code>] for the re note </p> <p>The socket, or the endpoint, returned by these functions may be in the process of closing, -and might not be further usable as a result. (Other functions will result in <a href="../../api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.)</p> +and might not be further usable as a result. (Other functions will result in <a href="../api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.)</p> </div> <h2 id="pipe-options"><a class="header" href="#pipe-options">Pipe Options</a></h2> <pre><code class="language-c">nng_err nng_pipe_get_bool(nng_pipe p, const char *opt, bool *valp); @@ -349,8 +349,8 @@ referenced by <em>valp</em>.</p> <p>These functions access an option as a specific type. The transport layer will have details about which options are available, and which type they may be accessed using.</p> <p>In the case of <code>nng_pipe_get_string</code>, the underlying string may only be valid for as long as the pipe is valid. -Thus, this function can only be safely called in a pipe event callback set up with <a href="../../api/pipe.html#pipe-notifications"><code>nng_pipe_notify</code></a>.</p> -<p>The <code>nng_pipe_get_strdup</code> function is like <code>nng_pipe_get_string</code>, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using <a href="../../api/memory.html#free-string"><code>nng_strfree</code></a>.</p> +Thus, this function can only be safely called in a pipe event callback set up with <a href="../api/pipe.html#pipe-notifications"><code>nng_pipe_notify</code></a>.</p> +<p>The <code>nng_pipe_get_strdup</code> function is like <code>nng_pipe_get_string</code>, but makes a copy into a newly allocated buffer, so that the string must be freed by the caller using <a href="../api/memory.html#free-string"><code>nng_strfree</code></a>.</p> <p>The <code>nng_pipe_get_strcpy</code> function is also like <code>nng_pipe_get_string</code>, but it makes a copy into a buffer supplied by the caller. The buffer is passed in <em>val</em>, and the size of the buffer is passed in <em>len</em>. The value of <em>len</em> must be large enough to hold the string and the terminating zero byte.</p> @@ -377,7 +377,7 @@ Each event may have at most one callback registered. Registering a callback implicitly unregisters any previously registered.</p> <p>The following pipe events are supported:</p> <div class="table-wrapper"><table><thead><tr><th>Event</th><th>Description</th></tr></thead><tbody> -<tr><td><a name="a019"></a><code>NNG_PIPE_EV_ADD_PRE</code><a name="NNG_PIPE_EV_ADD_PRE"></a></td><td>This event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using <a href="../../api/pipe.html#closing-a-pipe"><code>nng_pipe_close</code></a>) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.</td></tr> +<tr><td><a name="a019"></a><code>NNG_PIPE_EV_ADD_PRE</code><a name="NNG_PIPE_EV_ADD_PRE"></a></td><td>This event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using <a href="../api/pipe.html#closing-a-pipe"><code>nng_pipe_close</code></a>) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.</td></tr> <tr><td><a name="a020"></a><code>NNG_PIPE_EV_ADD_POST</code><a name="NNG_PIPE_EV_ADD_POST"></a></td><td>This event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.</td></tr> <tr><td><a name="a021"></a><code>NNG_PIPE_EV_REM_POST</code><a name="NNG_PIPE_EV_REM_POST"></a></td><td>This event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.</td></tr> </tbody></table> @@ -395,7 +395,7 @@ Doing so would thus result in a deadlock.</p> <span class="mdbook-alerts-icon"></span> tip </p> -<p>The callback <em>cb</em> may close a pipe for any reason by simply closing it using <a href="../../api/pipe.html#closing-a-pipe"><code>nng_pipe_close</code></a>. +<p>The callback <em>cb</em> may close a pipe for any reason by simply closing it using <a href="../api/pipe.html#closing-a-pipe"><code>nng_pipe_close</code></a>. For example, this might be done to prevent an unauthorized peer from connecting to the socket, if an authorization check made during <code>NNG_PIPE_EV_ADD_PRE</code> fails.</p> </div> diff --git a/ref/api/sock.html b/ref/api/sock.html index 81698cce..e0b4bef9 100644 --- a/ref/api/sock.html +++ b/ref/api/sock.html @@ -278,7 +278,7 @@ names of the socket’s protocol, and of the protocol peers of the socket use. The value stored in <em>name</em> is a fixed string located in program text, and must not be freed 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/sock.html#raw-mode-sockets">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> +<a href="../api/sock.html#raw-mode-sockets">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="opening-a-socket"><a class="header" href="#opening-a-socket">Opening a Socket</a></h2> <pre><code class="language-c">int nng_bus0_open(nng_socket *s); int nng_pub0_open(nng_socket *s); @@ -295,18 +295,18 @@ The constructors for sockets are protocol specific so please refer to protocol d for more specific information.</p> <p>The following functions open a socket in normal mode:</p> <ul> -<li><a name="a009"></a><code>nng_bus0_open</code> - <a href="../../proto/bus.html">BUS</a> version 0</li> -<li><a name="a010"></a><code>nng_pair0_open</code> - <a href="../../proto/pair.html">PAIR</a> version 0</li> -<li><a name="a011"></a><code>nng_pair1_open</code> - <a href="../../proto/pair.html">PAIR</a> version 1</li> -<li><a name="a012"></a><code>nng_pair1_open_poly</code> - <a href="../../proto/pair.html">PAIR</a> version 1, <a href="../../proto/pair.html#polyamorous-mode">polyamorous</a> mode</li> -<li><a name="a013"></a><code>nng_pub0_open</code> - <a href="../../proto/pub.html">PUB</a> version 0</li> -<li><a name="a014"></a><code>nng_pull0_open</code> - <a href="../../proto/pull.html">PULL</a> version 0</li> -<li><a name="a015"></a><code>nng_push0_open</code> - <a href="../../proto/push.html">PUSH</a> version 0</li> -<li><a name="a016"></a><code>nng_rep0_open</code> - <a href="../../proto/rep.html">REP</a> version 0</li> -<li><a name="a017"></a><code>nng_req0_open</code> - <a href="../../proto/req.html">REQ</a> version 0</li> -<li><a name="a018"></a><code>nng_respondent0_open</code> - <a href="../../proto/respondent.html">RESPONDENT</a> version 0</li> -<li><a name="a019"></a><code>nng_sub0_open</code> - <a href="../../proto/sub.html">SUB</a> version 0</li> -<li><a name="a020"></a><code>nng_surveyor0_open</code> - <a href="../../proto/surveyor.html">SURVEYOR</a> version 0</li> +<li><a name="a009"></a><code>nng_bus0_open</code> - <a href="../proto/bus.html">BUS</a> version 0</li> +<li><a name="a010"></a><code>nng_pair0_open</code> - <a href="../proto/pair.html">PAIR</a> version 0</li> +<li><a name="a011"></a><code>nng_pair1_open</code> - <a href="../proto/pair.html">PAIR</a> version 1</li> +<li><a name="a012"></a><code>nng_pair1_open_poly</code> - <a href="../proto/pair.html">PAIR</a> version 1, <a href="../proto/pair.html#polyamorous-mode">polyamorous</a> mode</li> +<li><a name="a013"></a><code>nng_pub0_open</code> - <a href="../proto/pub.html">PUB</a> version 0</li> +<li><a name="a014"></a><code>nng_pull0_open</code> - <a href="../proto/pull.html">PULL</a> version 0</li> +<li><a name="a015"></a><code>nng_push0_open</code> - <a href="../proto/push.html">PUSH</a> version 0</li> +<li><a name="a016"></a><code>nng_rep0_open</code> - <a href="../proto/rep.html">REP</a> version 0</li> +<li><a name="a017"></a><code>nng_req0_open</code> - <a href="../proto/req.html">REQ</a> version 0</li> +<li><a name="a018"></a><code>nng_respondent0_open</code> - <a href="../proto/respondent.html">RESPONDENT</a> version 0</li> +<li><a name="a019"></a><code>nng_sub0_open</code> - <a href="../proto/sub.html">SUB</a> version 0</li> +<li><a name="a020"></a><code>nng_surveyor0_open</code> - <a href="../proto/surveyor.html">SURVEYOR</a> version 0</li> </ul> <h2 id="raw-mode-sockets"><a class="header" href="#raw-mode-sockets">Raw Mode Sockets</a></h2> <pre><code class="language-c">int nng_bus0_open_raw(nng_socket *s); @@ -334,36 +334,36 @@ the protocol specific processing must be performed by the application.</p> tip </p> <p>Most applications do not need to use raw sockets. -The notable exception is when using <a href="../../TODO.html"><code>nng_device</code></a>, which requires raw sockets. -To obtain asynchronous behavior, consider using <a href="../../TODO.html">contexts</a> instead.</p> +The notable exception is when using <a href="../TODO.html"><code>nng_device</code></a>, which requires raw sockets. +To obtain asynchronous behavior, consider using <a href="../TODO.html">contexts</a> instead.</p> </div> -<p>The following functions open a socket in <a href="../../api/sock.html#raw-mode-sockets">raw</a> mode:</p> +<p>The following functions open a socket in <a href="../api/sock.html#raw-mode-sockets">raw</a> mode:</p> <ul> -<li><a name="a022"></a><code>nng_bus0_open_raw</code> - <a href="../../proto/bus.html">BUS</a> version 0, raw mode</li> -<li><a name="a023"></a><code>nng_pair0_open_raw</code> - <a href="../../proto/pair.html">PAIR</a> version 0, raw mode</li> -<li><a name="a024"></a><code>nng_pair1_open_raw</code> - <a href="../../proto/pair.html">PAIR</a> version 1, raw mode</li> -<li><a name="a025"></a><code>nng_pub0_open_raw</code> - <a href="../../proto/pub.html">PUB</a> version 0, raw mode</li> -<li><a name="a026"></a><code>nng_pull0_open_raw</code> - <a href="../../proto/pull.html">PULL</a> version 0, raw mode</li> -<li><a name="a027"></a><code>nng_push0_open_raw</code> - <a href="../../proto/push.html">PUSH</a> version 0, raw mode</li> -<li><a name="a028"></a><code>nng_rep0_open_raw</code> - <a href="../../proto/rep.html">REP</a> version 0, raw mode</li> -<li><a name="a029"></a><code>nng_req0_open_raw</code> - <a href="../../proto/req.html">REP</a> version 0, raw mode</li> -<li><a name="a030"></a><code>nng_respondent0_open_raw</code> - <a href="../../proto/respondent.html">RESPONDENT</a> version 0, raw mode</li> -<li><a name="a031"></a><code>nng_sub0_open_raw</code> - <a href="../../proto/sub.html">SUB</a> version 0, raw mode</li> -<li><a name="a032"></a><code>nng_surveyor0_open_raw</code> - <a href="../../proto/surveyor.html">SURVEYOR</a> version 0, raw mode</li> +<li><a name="a022"></a><code>nng_bus0_open_raw</code> - <a href="../proto/bus.html">BUS</a> version 0, raw mode</li> +<li><a name="a023"></a><code>nng_pair0_open_raw</code> - <a href="../proto/pair.html">PAIR</a> version 0, raw mode</li> +<li><a name="a024"></a><code>nng_pair1_open_raw</code> - <a href="../proto/pair.html">PAIR</a> version 1, raw mode</li> +<li><a name="a025"></a><code>nng_pub0_open_raw</code> - <a href="../proto/pub.html">PUB</a> version 0, raw mode</li> +<li><a name="a026"></a><code>nng_pull0_open_raw</code> - <a href="../proto/pull.html">PULL</a> version 0, raw mode</li> +<li><a name="a027"></a><code>nng_push0_open_raw</code> - <a href="../proto/push.html">PUSH</a> version 0, raw mode</li> +<li><a name="a028"></a><code>nng_rep0_open_raw</code> - <a href="../proto/rep.html">REP</a> version 0, raw mode</li> +<li><a name="a029"></a><code>nng_req0_open_raw</code> - <a href="../proto/req.html">REP</a> version 0, raw mode</li> +<li><a name="a030"></a><code>nng_respondent0_open_raw</code> - <a href="../proto/respondent.html">RESPONDENT</a> version 0, raw mode</li> +<li><a name="a031"></a><code>nng_sub0_open_raw</code> - <a href="../proto/sub.html">SUB</a> version 0, raw mode</li> +<li><a name="a032"></a><code>nng_surveyor0_open_raw</code> - <a href="../proto/surveyor.html">SURVEYOR</a> version 0, raw mode</li> </ul> <h2 id="closing-a-socket"><a class="header" href="#closing-a-socket">Closing a Socket</a></h2> <pre><code class="language-c">int nng_socket_close(nng_socket s); </code></pre> <p>The <a name="a033"></a><code>nng_socket_close</code> function closes a socket, releasing all resources associated with it. Any operations that are in progress will be terminated with -a result of <a href="../../api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.</p> +a result of <a href="../api/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> note </p> -<p>Closing a socket also invalidates any <a href="../../TODO.html">dialers</a>, <a href="../../TODO.html">listeners</a>, -<a href="../../api/pipe.html">pipes</a>, or <a href="../../TODO.html">contexts</a> associated with it.</p> +<p>Closing a socket also invalidates any <a href="../TODO.html">dialers</a>, <a href="../TODO.html">listeners</a>, +<a href="../api/pipe.html">pipes</a>, or <a href="../TODO.html">contexts</a> associated with it.</p> </div> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> @@ -396,8 +396,8 @@ messages over the socket <em>s</em>. The differences in their behaviors are as f <p>The semantics of what sending a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. Additionally, some protocols may not support sending at all or may require other pre-conditions first. -(For example, <a href="../../proto/rep.html">REP</a> sockets cannot normally send data until they have first received a request, -while <a href="../../proto/sub.html">SUB</a> sockets can only receive data and never send it.)</p> +(For example, <a href="../proto/rep.html">REP</a> sockets cannot normally send data until they have first received a request, +while <a href="../proto/sub.html">SUB</a> sockets can only receive data and never send it.)</p> </div> <h3 id="nng_send"><a class="header" href="#nng_send">nng_send</a></h3> <p>The <code>nng_send</code> function is the simplest to use, but is the least efficient. @@ -406,7 +406,7 @@ made up of zero or more of the following values:</p> <ul> <li><a name="a037"></a><code>NNG_FLAG_NONBLOCK</code>: <a name="NNG_FLAG_NONBLOCK"></a> If the socket cannot accept more data at this time, it does not block, but returns immediately -with a status of <a href="../../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>. If this flag is absent, the function will wait until data can be sent.</li> +with a status of <a href="../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>. If this flag is absent, the function will wait until data can be sent.</li> </ul> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> @@ -417,28 +417,28 @@ with a status of <a href="../../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</co be queues between the sender and the receiver. Furthermore, there is no guarantee that the message has actually been delivered. Finally, with some protocols, the semantic is implicitly <code>NNG_FLAG_NONBLOCK</code>, -such as with <a href="../../proto/pub.html">PUB</a> sockets, which are best-effort delivery only.</p> +such as with <a href="../proto/pub.html">PUB</a> sockets, which are best-effort delivery only.</p> </div> <h3 id="nng_sendmsg"><a class="header" href="#nng_sendmsg">nng_sendmsg</a></h3> <p>The <code>nng_sendmsg</code> function sends the <em>msg</em> over the socket <em>s</em>.</p> <p>If this function returns zero, then the socket will dispose of <em>msg</em> when the transmission is complete. If the function returns a non-zero status, then the call retains the responsibility for disposing of <em>msg</em>.</p> -<p>The <em>flags</em> can contain the value <a href="../../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket -cannot accept more data for sending. In such a case, it will return <a href="../../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> +<p>The <em>flags</em> can contain the value <a href="../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket +cannot accept more data for sending. In such a case, it will return <a href="../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> tip </p> -<p>This function is preferred over <a href="../../api/sock.html#nng_send"><code>nng_send</code></a>, as it gives access to the message structure and eliminates both +<p>This function is preferred over <a href="../api/sock.html#nng_send"><code>nng_send</code></a>, as it gives access to the message structure and eliminates both a data copy and allocation.</p> </div> <h3 id="nng_socket_send"><a class="header" href="#nng_socket_send">nng_socket_send</a></h3> -<p>The <code>nng_socket_send</code> function sends a message asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the socket <em>s</em>. -The message to send must have been set on <em>aio</em> using the <a href="../../api/aio.html#messages"><code>nng_aio_set_msg</code></a> function.</p> +<p>The <code>nng_socket_send</code> function sends a message asynchronously, using the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the socket <em>s</em>. +The message to send must have been set on <em>aio</em> using the <a href="../api/aio.html#messages"><code>nng_aio_set_msg</code></a> function.</p> <p>If the operation completes successfully, then the socket will have disposed of the message. However, if it fails, then callback of <em>aio</em> should arrange for a final disposition of the message. -(The message can be retrieved from <em>aio</em> with <a href="../../api/aio.html#messages"><code>nng_aio_get_msg</code></a>.)</p> +(The message can be retrieved from <em>aio</em> with <a href="../api/aio.html#messages"><code>nng_aio_get_msg</code></a>.)</p> <p>Note that callback associated with <em>aio</em> may be called <em>before</em> the message is finally delivered to the recipient. For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.</p> <div class="mdbook-alerts mdbook-alerts-tip"> @@ -448,7 +448,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or </p> <p>This is the preferred function to use for sending data on a socket. While it does require a few extra steps on the part of the application, the lowest latencies and highest performance will be achieved by using -this function instead of <a href="../../api/sock.html#nng_send"><code>nng_send</code></a> or <a href="../../api/sock.html#nng_sendmsg"><code>nng_sendmsg</code></a>.</p> +this function instead of <a href="../api/sock.html#nng_send"><code>nng_send</code></a> or <a href="../api/sock.html#nng_sendmsg"><code>nng_sendmsg</code></a>.</p> </div> <h2 id="receiving-messages"><a class="header" href="#receiving-messages">Receiving Messages</a></h2> <pre><code class="language-c">int nng_recv(nng_socket s, void *data, size_t *sizep, int flags); @@ -465,8 +465,8 @@ messages over the socket <em>s</em>. The differences in their behaviors are as f <p>The semantics of what receiving a message means varies from protocol to protocol, so examination of the protocol documentation is encouraged. Additionally, some protocols may not support receiving at all or may require other pre-conditions first. -(For example, <a href="../../proto/req.html">REQ</a> sockets cannot normally receive data until they have first sent a request, -while <a href="../../proto/pub.html">PUB</a> sockets can only send data and never receive it.)</p> +(For example, <a href="../proto/req.html">REQ</a> sockets cannot normally receive data until they have first sent a request, +while <a href="../proto/pub.html">PUB</a> sockets can only send data and never receive it.)</p> </div> <h3 id="nng_recv"><a class="header" href="#nng_recv">nng_recv</a></h3> <p>The <code>nng_recv</code> function is the simplest to use, but is the least efficient. @@ -476,23 +476,23 @@ It receives the content in <em>data</em>, as a message size (in bytes) of up to <ul> <li><a name="a041"></a><code>NNG_FLAG_NONBLOCK</code>: If the socket has no messages pending for reception at this time, it does not block, but returns immediately -with a status of <a href="../../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>. If this flag is absent, the function will wait until data can be received.</li> +with a status of <a href="../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>. If this flag is absent, the function will wait until data can be received.</li> </ul> <h3 id="nng_recvmsg"><a class="header" href="#nng_recvmsg">nng_recvmsg</a></h3> -<p>The <code>nng_recvmsg</code> function receives a message and stores a pointer to the <a href="../../api/msg.html#message-structure"><code>nng_msg</code></a> for that message in <em>msgp</em>.</p> -<p>The <em>flags</em> can contain the value <a href="../../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket -has no messages available to receive. In such a case, it will return <a href="../../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> +<p>The <code>nng_recvmsg</code> function receives a message and stores a pointer to the <a href="../api/msg.html#message-structure"><code>nng_msg</code></a> for that message in <em>msgp</em>.</p> +<p>The <em>flags</em> can contain the value <a href="../TODO.html"><code>NNG_FLAG_NONBLOCK</code></a>, indicating that the function should not wait if the socket +has no messages available to receive. In such a case, it will return <a href="../api/errors.html#NNG_EAGAIN"><code>NNG_EAGAIN</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> tip </p> -<p>This function is preferred over <a href="../../TODO.html"><code>nng_recv</code></a>, as it gives access to the message structure and eliminates both +<p>This function is preferred over <a href="../TODO.html"><code>nng_recv</code></a>, as it gives access to the message structure and eliminates both a data copy and allocation.</p> </div> <h3 id="nng_socket_recv"><a class="header" href="#nng_socket_recv">nng_socket_recv</a></h3> -<p>The <code>nng_socket_send</code> function receives a message asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the socket <em>s</em>. -On success, the received message can be retrieved from the <em>aio</em> using the <a href="../../api/aio.html#messages"><code>nng_aio_get_msg</code></a> function.</p> +<p>The <code>nng_socket_send</code> function receives a message asynchronously, using the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, over the socket <em>s</em>. +On success, the received message can be retrieved from the <em>aio</em> using the <a href="../api/aio.html#messages"><code>nng_aio_get_msg</code></a> function.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -508,7 +508,7 @@ Failure to do so will leak the memory.</p> </p> <p>This is the preferred function to use for receiving data on a socket. While it does require a few extra steps on the part of the application, the lowest latencies and highest performance will be achieved by using -this function instead of <a href="../../TODO.html"><code>nng_recv</code></a> or <a href="../../api/sock.html#nng_recvmsg"><code>nng_recvmsg</code></a>.</p> +this function instead of <a href="../TODO.html"><code>nng_recv</code></a> or <a href="../api/sock.html#nng_recvmsg"><code>nng_recvmsg</code></a>.</p> </div> <h2 id="socket-options"><a class="header" href="#socket-options">Socket Options</a></h2> <pre><code class="language-c">int nng_socket_get_bool(nng_socket s, const char *opt, bool *valp); @@ -533,16 +533,16 @@ are available, whether they can be read or written, and the appropriate type to note </p> <p>Socket options are are used to tune the behavior of the higher level protocol. To change the options -for an underlying transport, the option should be set on the <a href="../../TODO.html">dialer</a> or <a href="../../TODO.html">listener</a> instead of the <a href="../../TODO.html">socket</a>.</p> +for an underlying transport, the option should be set on the <a href="../TODO.html">dialer</a> or <a href="../TODO.html">listener</a> instead of the <a href="../TODO.html">socket</a>.</p> </div> <h3 id="common-options"><a class="header" href="#common-options">Common Options</a></h3> <p>The following options are available for many protocols, and always use the same types and semantics described below.</p> <div class="table-wrapper"><table><thead><tr><th>Option</th><th>Type</th><th>Description</th></tr></thead><tbody> -<tr><td><code>NNG_OPT_MAXTTL</code><a name="NNG_OPT_MAXTTL"></a></td><td><code>int</code></td><td>Maximum number of traversals across an <a href="../../TODO.html"><code>nng_device</code></a> device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.</td></tr> -<tr><td><code>NNG_OPT_RECONNMAXT</code><a name="NNG_OPT_RECONNMAXT"></a></td><td><code>nng_duration</code></td><td>Maximum time <a href="../../TODO.html">dialers</a> will delay before trying after failing to connect.</td></tr> -<tr><td><code>NNG_OPT_RECONNMINT</code><a name="NNG_OPT_RECONNMINT"></a></td><td><code>nng_duration</code></td><td>Minimum time <a href="../../TODO.html">dialers</a> will delay before trying after failing to connect.</td></tr> +<tr><td><code>NNG_OPT_MAXTTL</code><a name="NNG_OPT_MAXTTL"></a></td><td><code>int</code></td><td>Maximum number of traversals across an <a href="../TODO.html"><code>nng_device</code></a> device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.</td></tr> +<tr><td><code>NNG_OPT_RECONNMAXT</code><a name="NNG_OPT_RECONNMAXT"></a></td><td><code>nng_duration</code></td><td>Maximum time <a href="../TODO.html">dialers</a> will delay before trying after failing to connect.</td></tr> +<tr><td><code>NNG_OPT_RECONNMINT</code><a name="NNG_OPT_RECONNMINT"></a></td><td><code>nng_duration</code></td><td>Minimum time <a href="../TODO.html">dialers</a> will delay before trying after failing to connect.</td></tr> <tr><td><code>NNG_OPT_RECVBUF</code><a name="NNG_OPT_RECVBUF"></a></td><td><code>int</code></td><td>Maximum number of messages (0-8192) to buffer locally when receiving.</td></tr> -<tr><td><code>NNG_OPT_RECVMAXSZ</code><a name="NNG_OPT_RECVMAXSZ"></a></td><td><code>size_t</code></td><td>Maximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on <a href="../../TODO.html">dialers</a> and <a href="../../TODO.html">listeners</a>.</td></tr> +<tr><td><code>NNG_OPT_RECVMAXSZ</code><a name="NNG_OPT_RECVMAXSZ"></a></td><td><code>size_t</code></td><td>Maximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on <a href="../TODO.html">dialers</a> and <a href="../TODO.html">listeners</a>.</td></tr> <tr><td><code>NNG_OPT_RECVTIMEO</code><a name="NNG_OPT_RECVTIMEO"></a></td><td><code>nng_duration</code></td><td>Default timeout (ms) for receiving messages.</td></tr> <tr><td><code>NNG_OPT_SENDBUF</code><a name="NNG_OPT_SENDBUF"></a></td><td><code>int</code></td><td>Maximum number of messages (0-8192) to buffer when sending messages.</td></tr> <tr><td><code>NNG_OPT_SENDTIMEO</code><a name="NNG_OPT_SENDTIMEO"></a></td><td><code>nng_duration</code></td><td>Default timeout (ms) for sending messages.</td></tr> @@ -554,8 +554,8 @@ for an underlying transport, the option should be set on the <a href="../../TODO <span class="mdbook-alerts-icon"></span> note </p> -<p>The <code>NNG_OPT_RECONNMAXT</code>, <code>NNG_OPT_RECONNMINT</code>, and <code>NNG_OPT_RECVMAXSZ</code> options are just the initial defaults that <a href="../../TODO.html">dialers</a> -(and for <code>NNG_OPT_RECVMAXSZ</code> also <a href="../../TODO.html">listeners</a>) +<p>The <code>NNG_OPT_RECONNMAXT</code>, <code>NNG_OPT_RECONNMINT</code>, and <code>NNG_OPT_RECVMAXSZ</code> options are just the initial defaults that <a href="../TODO.html">dialers</a> +(and for <code>NNG_OPT_RECVMAXSZ</code> also <a href="../TODO.html">listeners</a>) will use. After the dialer or listener is created, changes to the socket’s value will have no affect on that dialer or listener.</p> </div> <h2 id="polling-socket-events"><a class="header" href="#polling-socket-events">Polling Socket Events</a></h2> @@ -581,7 +581,7 @@ were available in previous versions of NNG.</p> <span class="mdbook-alerts-icon"></span> note </p> -<p>These functions are not compatible with <a href="../../TODO.html">contexts</a>.</p> +<p>These functions are not compatible with <a href="../TODO.html">contexts</a>.</p> </div> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> @@ -598,7 +598,7 @@ messages on the socket.</p> 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/aio.html">asynchronous I/O</a> +have a negative impact on performance and latency. It is preferable to use <a href="../api/aio.html">asynchronous I/O</a> when possible.</p> </div> <h2 id="examples"><a class="header" href="#examples">Examples</a></h2> @@ -606,7 +606,7 @@ when possible.</p> <pre><code class="language-c">nng_socket s = NNG_SOCKET_INITIALIZER; </code></pre> <h3 id="example-2-publishing-a-timestamp"><a class="header" href="#example-2-publishing-a-timestamp">Example 2: Publishing a Timestamp</a></h3> -<p>This example demonstrates the use of <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, <a href="../../api/sock.html#nng_socket_send"><code>nng_socket_send</code></a>, and <a href="../../api/time.html"><code>nng_sleep_aio</code></a> to +<p>This example demonstrates the use of <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, <a href="../api/sock.html#nng_socket_send"><code>nng_socket_send</code></a>, and <a href="../api/time.html"><code>nng_sleep_aio</code></a> to build a service that publishes a timestamp at one second intervals. Error handling is elided for the sake of clarity.</p> <pre><code class="language-c">#include <stdlib.h> @@ -657,7 +657,7 @@ int main(int argc, char **argv) { } </code></pre> <h3 id="example-3-watching-a-periodic-timestamp"><a class="header" href="#example-3-watching-a-periodic-timestamp">Example 3: Watching a Periodic Timestamp</a></h3> -<p>This example demonstrates the use of <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, <a href="../../api/sock.html#nng_socket_recv"><code>nng_socket_recv</code></a>, to build a client to +<p>This example demonstrates the use of <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, <a href="../api/sock.html#nng_socket_recv"><code>nng_socket_recv</code></a>, to build a client to watch for messages received from the service created in Example 2. Error handling is elided for the sake of clarity.</p> <pre><code class="language-c">#include <stdlib.h> diff --git a/ref/api/stats.html b/ref/api/stats.html index aa0eeec9..2f7a5534 100644 --- a/ref/api/stats.html +++ b/ref/api/stats.html @@ -278,7 +278,7 @@ subject to change at any time and without notice.</p> </code></pre> <p>The <a name="a003"></a><code>nng_stats_get</code> function takes a snapshot of the statistics for the system and returns it through the pointer <em>statsp</em>. -This function may return <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if memory is exhausted, or <a href="../../api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> if the statistics +This function may return <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a> if memory is exhausted, or <a href="../api/errors.html#NNG_ENOTSUP"><code>NNG_ENOTSUP</code></a> if the statistics support is not enabled in the build, but is otherwise expected to return zero.</p> <h2 id="freeing-a-snapshot"><a class="header" href="#freeing-a-snapshot">Freeing a Snapshot</a></h2> <pre><code class="language-c">void nng_stats_free(nng_stat *stat); @@ -312,8 +312,8 @@ const nng_stat *nng_stat_find_listener(const nng_stat *stat, nng_dialer listener const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket); </code></pre> <p>Sometimes it is easiest to search for a specific statistic, matching by name, -or possibly to find the tree of statistics associated with a specific <a href="../../TODO.html">socket</a>, -<a href="../../TODO.html">dialer</a>, or <a href="../../TODO.html">listener</a>.</p> +or possibly to find the tree of statistics associated with a specific <a href="../TODO.html">socket</a>, +<a href="../TODO.html">dialer</a>, or <a href="../TODO.html">listener</a>.</p> <p>The <code>nng_stat_find</code> functions are provided for this purpose.</p> <p>The <a name="a008"></a><code>nng_stat_find</code> function returns the first statistic within the subtree of statistics <em>stat</em>, with the given <em>name</em>. If no such statistic can be found, <code>NULL</code> @@ -347,8 +347,8 @@ statistics tree.</p> The statistic is a counter that only increments. Usually the change in the value of the statistic is more interesting (as a rate) than the absolute value at any given time. The value should -be obtained using <a href="../../api/stats.html#statistic-value"><code>nng_stat_value</code></a>. -The units will be given by the value returned from <a href="../../api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p> +be obtained using <a href="../api/stats.html#statistic-value"><code>nng_stat_value</code></a>. +The units will be given by the value returned from <a href="../api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p> </li> <li> <p><a name="a017"></a><code>NNG_STAT_LEVEL</code>: <a name="NNG_STAT_LEVEL"></a> @@ -357,25 +357,25 @@ to a specific value at a specific time. For example, this may represent the number of messages currently queued for some operation, or the link speed of a network interface. Most often the absolute value is more interesting than the change in the value over time. Again the value can be obtained with -<a href="../../api/stats.html#statistic-value"><code>nng_stat_value</code></a>, and any appropriate unit of measurement -with <a href="../../api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p> +<a href="../api/stats.html#statistic-value"><code>nng_stat_value</code></a>, and any appropriate unit of measurement +with <a href="../api/stats.html#statistic-units"><code>nng_stat_unit</code></a>.</p> </li> <li> <p><a name="a018"></a><code>NNG_STAT_STRING</code>: <a name="NNG_STAT_STRING"></a> The statistic is a string, such as a name. The value -of the string can be obtained with <a href="../../api/stats.html#statistic-value"><code>nng_stat_string</code></a>. +of the string can be obtained with <a href="../api/stats.html#statistic-value"><code>nng_stat_string</code></a>. The value of this string -will remain valid until the snapshot is deallocated with <a href="../../api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>.</p> +will remain valid until the snapshot is deallocated with <a href="../api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>.</p> </li> <li> <p><a name="a019"></a><code>NNG_STAT_BOOLEAN</code>: <a name="NNG_STAT_BOOLEAN"></a> The value of the statistic is a truth value (either <code>true</code> -or <code>false</code>) and can be obtained with <a href="../../api/stats.html#statistic-value"><code>nng_stat_bool</code></a>.</p> +or <code>false</code>) and can be obtained with <a href="../api/stats.html#statistic-value"><code>nng_stat_bool</code></a>.</p> </li> <li> <p><a name="a020"></a><code>NNG_STAT_ID</code>: <a name="NNG_STAT_ID"></a> The value of the statistic is a numeric identifier, such as a socket -identifier. The value can be obtained with <a href="../../api/stats.html#statistic-value"><code>nng_stat_value</code></a>, +identifier. The value can be obtained with <a href="../api/stats.html#statistic-value"><code>nng_stat_value</code></a>, and will be fixed for the life of the statistic.</p> </li> </ul> @@ -386,18 +386,18 @@ bool nng_stat_bool(const nng_stat *stat); </code></pre> <p>These functions return the value associated with the statistic.</p> <p>The <a name="a021"></a><code>nng_stat_value</code> function returns the the numeric value for the statistic <em>stat</em> -of type <a href="../../api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a>, <a href="../../api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>, or <a href="../../api/stats.html#NNG_STAT_ID"><code>NNG_STAT_ID</code></a>. +of type <a href="../api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a>, <a href="../api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>, or <a href="../api/stats.html#NNG_STAT_ID"><code>NNG_STAT_ID</code></a>. If <em>stat</em> is not one of these types, then it returns zero.</p> <p>The <a name="a022"></a><code>nng_stat_bool</code> function returns the Boolean value (either <code>true</code> or <code>false</code>) for the statistic <em>stat</em> of -type <a href="../../api/stats.html#NNG_STAT_BOOLEAN"><code>NNG_STAT_BOOLEAN</code></a>. If the statistics is not of this type, then it returns <code>false</code>.</p> +type <a href="../api/stats.html#NNG_STAT_BOOLEAN"><code>NNG_STAT_BOOLEAN</code></a>. If the statistics is not of this type, then it returns <code>false</code>.</p> <p>The <a name="a023"></a><code>nng_stat_string</code> function returns a pointer to a string value for the statistic <em>stat</em>, -of type <a href="../../api/stats.html#statistic-value"><code>NNG_STAT_STRING</code></a>. This string will remain valid until the snapshot that -<em>stat</em> was collected with is deallocated with <a href="../../api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>. If the statistic +of type <a href="../api/stats.html#statistic-value"><code>NNG_STAT_STRING</code></a>. This string will remain valid until the snapshot that +<em>stat</em> was collected with is deallocated with <a href="../api/stats.html#freeing-a-snapshot"><code>nng_stats_free</code></a>. If the statistic is not of type <code>NNG_STAT_STRING</code>, then <code>NULL</code> is returned.</p> <h2 id="statistic-units"><a class="header" href="#statistic-units">Statistic Units</a></h2> <pre><code class="language-c">int nng_stat_unit(const nng_stat *stat); </code></pre> -<p>For statistics of type <a href="../../api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a> or <a href="../../api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>, +<p>For statistics of type <a href="../api/stats.html#NNG_STAT_COUNTER"><code>NNG_STAT_COUNTER</code></a> or <a href="../api/stats.html#NNG_STAT_LEVEL"><code>NNG_STAT_LEVEL</code></a>, it is often useful to know what that quantity being reported measures. The following units may be returned from <a name="a024"></a><code>nng_stat_unit</code> for such a statistic:</p> <ul> @@ -413,9 +413,9 @@ The following units may be returned from <a name="a024"></a><code>nng_stat_unit< <p>Statistics have a timestamp indicating when the value was sampled, obtained via <a name="a030"></a><code>nng_stat_timestamp</code>. The timestamp is given in in milliseconds since a reference time, and the reference time used -here is the same reference time used for <a href="../../api/time.html#get-the-current-time"><code>nng_clock</code></a>.</p> +here is the same reference time used for <a href="../api/time.html#get-the-current-time"><code>nng_clock</code></a>.</p> <h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2> -<p><a href="../../api/time.html#get-the-current-time"><code>nng_clock</code></a></p> +<p><a href="../api/time.html#get-the-current-time"><code>nng_clock</code></a></p> <!-- NOTE: This assumes that any page referencing this is located in a directory two levels down. Meaning ./api/somefile.md or similar. mdbook cannot accommodate links that are called from diff --git a/ref/api/stream.html b/ref/api/stream.html index 25ca66bc..fd8de778 100644 --- a/ref/api/stream.html +++ b/ref/api/stream.html @@ -267,26 +267,26 @@ using these Streams APIs.</p> 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/pipe.html">pipe</a> object created on a <a href="../../TODO.html">socket</a> using -the <a href="../../TODO.html"><code>nng_listen</code></a>, <a href="../../TODO.html"><code>nng_dial</code></a> or related functions.</p> +should not be confused with a <a href="../api/pipe.html">pipe</a> object created on a <a href="../TODO.html">socket</a> using +the <a href="../TODO.html"><code>nng_listen</code></a>, <a href="../TODO.html"><code>nng_dial</code></a> 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/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, -which must have been previously set using <a href="../../api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>.</p> +The data is sent from the scatter/gather vector located in the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, +which must have been previously set using <a href="../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/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, -which must have been previously set using <a href="../../api/aio.html#scatter-gather-vectors"><code>nng_aio_set_iov</code></a>.</p> +into the scatter/gather vector located in the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>, +which must have been previously set using <a href="../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/aio.html#result-of-operation"><code>nng_aio_result</code></a>.</p> +result may be obtained via <a href="../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/aio.html#result-of-operation"><code>nng_aio_count</code></a>.</p> +The actual number of bytes transferred can be determined with <a href="../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); @@ -294,8 +294,8 @@ 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/stream.html#sending-and-receiving-data"><code>nng_stream_send</code></a> or <a href="../../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/errors.html#NNG_ECLOSED"><code>NNG_ECLOSED</code></a>.</p> +as <a href="../api/stream.html#sending-and-receiving-data"><code>nng_stream_send</code></a> or <a href="../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/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 @@ -310,7 +310,7 @@ stream itself.</p> </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/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> when it is created.</p> +completion function registered with an <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> when it is created.</p> </div> <h2 id="getting-stream-options"><a class="header" href="#getting-stream-options">Getting Stream Options</a></h2> <pre><code class="language-c">nng_err nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp); @@ -338,7 +338,7 @@ typedef struct nng_stream_listener nng_stream_listener; </code></pre> <p><a name="a014"></a> The <a name="a015"></a><code>nng_stream_listener</code> object and <a name="a016"></a><code>nng_stream_listener</code> objects can be thought of as factories that -create <a href="../../api/stream.html#stream-type"><code>nng_stream</code></a> streams.</p> +create <a href="../api/stream.html#stream-type"><code>nng_stream</code></a> streams.</p> <p>The <code>nng_stream_listener</code> object a handle to a listener, which creates streams by accepting incoming connection requests. In a BSD socket implementation, this is the entity responsible for doing <a name="a017"></a><code>bind</code>, <a name="a018"></a><code>listen</code> and <a name="a019"></a><code>accept</code>. Normally a listener may be used to accept multiple, possibly many, concurrent connections.</p> @@ -352,10 +352,10 @@ nng_err nng_stream_listener_alloc(nng_stream_listener **lstenerp, const char *ur nng_err nng_stream_listener_alloc_url(nng_stream_listener **listenerp, const nng_url *url); </code></pre> <p>The <a name="a022"></a><code>nng_stream_dialer_alloc</code> and <a name="a023"></a><code>nng_stream_dialer_alloc_url</code> functions create a stream dialer, associated the -<a name="a024"></a>URL specified by <em>url</em> represented as a string, or as an <a href="../../api/url.html#url-structure"><code>nng_url</code></a> object, respectively. The dialer is returned in the location +<a name="a024"></a>URL specified by <em>url</em> represented as a string, or as an <a href="../api/url.html#url-structure"><code>nng_url</code></a> object, respectively. The dialer is returned in the location <em>dialerp</em> references.</p> <p>The <a name="a025"></a><code>nng_stream_listener_alloc</code> and <a name="a026"></a><code>nng_stream_listener_alloc_url</code> functions create a stream listener, associated the -URL specified by <em>url</em> represented as a string, or as an <a href="../../api/url.html#url-structure"><code>nng_url</code></a> object, respectively. The listener is returned in the location +URL specified by <em>url</em> represented as a string, or as an <a href="../api/url.html#url-structure"><code>nng_url</code></a> object, respectively. The listener is returned in the location <em>listenerp</em> references.</p> <h3 id="example-1-creating-a-tcp-listener"><a class="header" href="#example-1-creating-a-tcp-listener">Example 1: Creating a TCP Listener</a></h3> <p>This shows creating a TCP listener that listens on <code>INADDR_ANY</code>, port 444.</p> @@ -390,15 +390,15 @@ callbacks are running that could reference an object after it is deallocated.</p <h2 id="making-outgoing-connections"><a class="header" href="#making-outgoing-connections">Making Outgoing Connections</a></h2> <pre><code class="language-c">void nng_stream_dialer_dial(nng_stream_dialer *dialer, nng_aio *aio); </code></pre> -<p>The <a name="a033"></a><code>nng_stream_dialer_dial</code> initiates an outgoing connection asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>. -If it successfully establishes a connection, it creates an <a href="../../api/stream.html#stream-type"><code>nng_stream</code></a>, which can be obtained as the first -output result on <em>aio</em> using the <a href="../../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> function with index zero.</p> +<p>The <a name="a033"></a><code>nng_stream_dialer_dial</code> initiates an outgoing connection asynchronously, using the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>. +If it successfully establishes a connection, it creates an <a href="../api/stream.html#stream-type"><code>nng_stream</code></a>, which can be obtained as the first +output result on <em>aio</em> using the <a href="../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> function with index zero.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> tip </p> -<p>An <a href="../../api/stream.html#stream-factories"><code>nng_stream_dialer</code></a> can be used multiple times to make multiple concurrent connection requests, but +<p>An <a href="../api/stream.html#stream-factories"><code>nng_stream_dialer</code></a> can be used multiple times to make multiple concurrent connection requests, but they all must reference the same URL.</p> </div> <h3 id="example-3-connecting-to-google"><a class="header" href="#example-3-connecting-to-google">Example 3: Connecting to Google</a></h3> @@ -426,12 +426,12 @@ void nng_stream_listener_accept(nng_stream_listener *listener, nng_aio *aio); </code></pre> <p>Accepting incoming connections is performed in two steps. The first step, <a name="a034"></a><code>nng_stream_listener_listen</code> is to setup for listening. For a TCP implementation of this, for example, this would perform the <code>bind</code> and the <code>listen</code> steps. This will bind -to the address represented by the URL that was specific when the listener was created with <a href="../../api/stream.html#creating-a-stream-factory"><code>nng_stream_listener_alloc</code></a>.</p> -<p>In the second step, <a name="a035"></a><code>nng_stream_listener_accept</code> accepts an incoming connection on <em>listener</em> asynchronously, using the <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>. -If an incoming connection is accepted, it will be represented as an <a href="../../api/stream.html#stream-type"><code>nng_stream</code></a>, which can be obtained from the <em>aio</em> as the first -output result using the <a href="../../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> function with index zero.</p> +to the address represented by the URL that was specific when the listener was created with <a href="../api/stream.html#creating-a-stream-factory"><code>nng_stream_listener_alloc</code></a>.</p> +<p>In the second step, <a name="a035"></a><code>nng_stream_listener_accept</code> accepts an incoming connection on <em>listener</em> asynchronously, using the <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> <em>aio</em>. +If an incoming connection is accepted, it will be represented as an <a href="../api/stream.html#stream-type"><code>nng_stream</code></a>, which can be obtained from the <em>aio</em> as the first +output result using the <a href="../api/aio.html#inputs-and-outputs"><code>nng_aio_get_output</code></a> function with index zero.</p> <h3 id="example-3-accepting-an-inbound-stream"><a class="header" href="#example-3-accepting-an-inbound-stream">Example 3: Accepting an Inbound Stream</a></h3> -<p>For clarity this example uses a synchronous approach using <a href="../../api/aio.html#wait-for-completion"><code>nng_aio_wait</code></a>, but a typical server application +<p>For clarity this example uses a synchronous approach using <a href="../api/aio.html#wait-for-completion"><code>nng_aio_wait</code></a>, but a typical server application would most likely use a callback to accept the incoming stream, and start another instance of <code>nng_stream_listener_accept</code>.</p> <pre><code class="language-c">nng_aio *aio; nng_listener *listener; @@ -518,10 +518,10 @@ need not retain the value referenced once the function returns.</p> <p>In the case of <code>nng_stream_dialer_set_addr</code> and <code>nng_stream_listener_set_addr</code>, the contents of <em>addr</em> are copied if necessary, so that the caller need not retain the value referenced once the function returns.</p> <h3 id="example-4-socket-activation"><a class="header" href="#example-4-socket-activation">Example 4: Socket Activation<a name="socket-activation"></a></a></h3> -<p>Some <a href="../../api/stream.html#stream-factories"><code>nng_stream_listener</code></a> objects, depending on the underlying transport and platform, can support a technique known as “<a name="a060"></a>socket activation”, +<p>Some <a href="../api/stream.html#stream-factories"><code>nng_stream_listener</code></a> objects, depending on the underlying transport and platform, can support a technique known as “<a name="a060"></a>socket activation”, where the file descriptor used for listening and accepting is supplied externally, such as by a system service manager. In this case, the application supplies the file descriptor or <code>SOCKET</code> object using the <a name="a061"></a><code>NNG_OPT_LISTEN_FD</code> option, -instead of calling <a href="../../api/stream.html#accepting-incoming-connections"><code>nng_stream_listener_listen</code></a>.</p> +instead of calling <a href="../api/stream.html#accepting-incoming-connections"><code>nng_stream_listener_listen</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-tip"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -548,21 +548,21 @@ nng_err nng_stream_dialer_set_tls(nng_stream_listener *dialer, nng_tls_config *t nng_err nng_stream_listener_get_tls(nng_stream_listener *listener, nng_tls_config **tlsp); nng_err nng_stream_listener_set_tls(nng_stream_listener *listener, nng_tls_config *tls); </code></pre> -<p>Both <a href="../../api/stream.html#stream-factories"><code>nng_stream_dialer</code></a> and <a href="../../api/stream.html#stream-factories"><code>nng_stream_listener</code></a> objects may support configuration of <a name="a062"></a>TLS parameters. +<p>Both <a href="../api/stream.html#stream-factories"><code>nng_stream_dialer</code></a> and <a href="../api/stream.html#stream-factories"><code>nng_stream_listener</code></a> objects may support configuration of <a name="a062"></a>TLS parameters. The <a name="a063"></a><code>nng_stream_dialer_set_tls</code> and <a name="a064"></a><code>nng_stream_listener_set_tls</code> functions support setting the -configuration of a <a href="../../TODO.html"><code>nng_tls_config</code></a> object supplied by <em>tls</em> on <em>dialer</em> or <em>listener</em>. -This must be performed before the <em>listener</em> starts listening with <a href="../../api/stream.html#accepting-incoming-connections"><code>nng_stream_listener_listen</code></a>, or the dialer starts an outgoing connection -as a result of <a href="../../api/stream.html#making-outgoing-connections"><code>nng_stream_dialer_dial</code></a>.</p> +configuration of a <a href="../TODO.html"><code>nng_tls_config</code></a> object supplied by <em>tls</em> on <em>dialer</em> or <em>listener</em>. +This must be performed before the <em>listener</em> starts listening with <a href="../api/stream.html#accepting-incoming-connections"><code>nng_stream_listener_listen</code></a>, or the dialer starts an outgoing connection +as a result of <a href="../api/stream.html#making-outgoing-connections"><code>nng_stream_dialer_dial</code></a>.</p> <p>The configuration object that was previously established (which may be a default if one was not explicitly configured) can be obtained with the <a name="a065"></a><code>nng_stream_dialer_get_tls</code> and <a name="a066"></a><code>nng_stream_listener_get_tls</code>. -They will return a pointer to the <a href="../../TODO.html"><code>nng_tls_config</code></a> object in question at the location referenced by <em>tlsp</em>.</p> +They will return a pointer to the <a href="../TODO.html"><code>nng_tls_config</code></a> object in question at the location referenced by <em>tlsp</em>.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> note </p> <p>TLS configuration cannot be changed once it has started being used by a listener or dialer. This applies to -both configuring a different TLS configuration object, as well as mutating the existing <a href="../../TODO.html"><code>nng_tls_config</code></a> object.</p> +both configuring a different TLS configuration object, as well as mutating the existing <a href="../TODO.html"><code>nng_tls_config</code></a> object.</p> </div> <!-- NOTE: This assumes that any page referencing this is located in a directory two levels down. Meaning ./api/somefile.md or diff --git a/ref/api/synch.html b/ref/api/synch.html index eb8672a2..17d8788a 100644 --- a/ref/api/synch.html +++ b/ref/api/synch.html @@ -245,32 +245,32 @@ </style> <h1 id="synchronization-primitives"><a class="header" href="#synchronization-primitives">Synchronization Primitives</a></h1> <p>In order to allow safely accessing shared state, or to allow coordination between -different <a href="../../api/thread.html">threads</a>, <em>NNG</em> provides <a name="a001"></a>synchronization primitives in the +different <a href="../api/thread.html">threads</a>, <em>NNG</em> provides <a name="a001"></a>synchronization primitives in the form of mutual exclusion locks and condition variables.</p> <p>Correct use of these primitives will be needed when accessing shared state from -threads, or from callback functions associated with <a href="../../api/aio.html">asynchronous operations</a>. +threads, or from callback functions associated with <a href="../api/aio.html">asynchronous operations</a>. (The need to do this in callbacks is because the callback may be executed under a task thread other than the submitting thread.)</p> <h2 id="mutual-exclusion-lock"><a class="header" href="#mutual-exclusion-lock">Mutual Exclusion Lock</a></h2> <pre><code class="language-c">typedef struct nng_mtx nng_mtx; </code></pre> <p>Mutual exclusion locks, or <a name="a002"></a>mutex locks, represented by the <a name="a003"></a><code>nng_mtx</code> structure, -allow only a single <a href="../../api/thread.html">thread</a> to lock “own” the lock, acquired by <a href="../../api/synch.html#acquiring-a-mutex"><code>nng_mtx_lock</code></a>. +allow only a single <a href="../api/thread.html">thread</a> to lock “own” the lock, acquired by <a href="../api/synch.html#acquiring-a-mutex"><code>nng_mtx_lock</code></a>. Any other thread trying to acquire the same mutex will wait until the owner has released the mutex -by calling <a href="../../api/synch.html#releasing-a-mutex"><code>nng_mtx_unlock</code></a>.</p> +by calling <a href="../api/synch.html#releasing-a-mutex"><code>nng_mtx_unlock</code></a>.</p> <h3 id="creating-a-mutex"><a class="header" href="#creating-a-mutex">Creating a Mutex</a></h3> <pre><code class="language-c">int nng_mutx_alloc(nng_mt **mtxp); </code></pre> <p>A mutex can be created by allocating one with <a name="a004"></a><code>nng_mtx_lock</code>. On success, a pointer to the mutex is returned through <em>mtxp</em>. This function can fail due to insufficient memory or resources, in which -case it will return <a href="../../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>. Otherwise it will succeed and return zero.</p> +case it will return <a href="../api/errors.html#NNG_ENOMEM"><code>NNG_ENOMEM</code></a>. Otherwise it will succeed and return zero.</p> <h3 id="destroying-a-mutex"><a class="header" href="#destroying-a-mutex">Destroying a Mutex</a></h3> <pre><code class="language-c">void nng_mtx_free(nng_mtx *mtx); </code></pre> <p>When no longer needed, a mutex can be deallocated and its resources returned to the caller, by calling <a name="a005"></a><code>nng_mtx_free</code>. The mutex must not be locked -by any <a href="../../api/thread.html">thread</a> when calling this function.</p> +by any <a href="../api/thread.html">thread</a> when calling this function.</p> <h3 id="acquiring-a-mutex"><a class="header" href="#acquiring-a-mutex">Acquiring a Mutex</a></h3> <pre><code class="language-c">void nng_mtx_lock(nng_mtx *mtx); </code></pre> @@ -288,7 +288,7 @@ If it does attempt to do so, the result will be a single party deadlock.</p> <pre><code class="language-c">void nng_mtx_unlock(nng_mtx *mtx); </code></pre> <p>The <a name="a007"></a><code>nng_mtx_unlock</code> function releases a mutex that the calling thread has previously -acquired with <a href="../../api/synch.html#acquiring-a-mutex"><code>nng_mtx_lock</code></a>.</p> +acquired with <a href="../api/synch.html#acquiring-a-mutex"><code>nng_mtx_lock</code></a>.</p> <div class="mdbook-alerts mdbook-alerts-important"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> @@ -301,7 +301,7 @@ that acquired the mutex to begin with.</p> <pre><code class="language-c">typedef struct nng_cv nng_cv; </code></pre> <p>The <a name="a008"></a><code>nng_cv</code> structure implements a <a name="a009"></a>condition variable, associated with the -the <a href="../../api/synch.html#mutual-exclusion-lock">mutex</a> <em>mtx</em> which was supplied when it was created.</p> +the <a href="../api/synch.html#mutual-exclusion-lock">mutex</a> <em>mtx</em> which was supplied when it was created.</p> <p>Condition variables provide for a way to wait on an arbitrary condition, and to be woken when the condition is signaled. The mutex is dropped while the caller is asleep, and reacquired atomically when the caller @@ -329,16 +329,16 @@ void nng_cv_wait(nng_cv *cv); </code></pre> <p>The <a name="a012"></a><code>nng_cv_until</code> and <a name="a013"></a><code>nng_cv_wait</code> functions put the caller to sleep until the condition variable <em>cv</em> is signaled, or (in the case of <code>nng_cv_until</code>), the specified time <em>when</em> -(as determined by <a href="../../api/time.html#get-the-current-time"><code>nng_clock</code></a> is reached.</p> +(as determined by <a href="../api/time.html#get-the-current-time"><code>nng_clock</code></a> is reached.</p> <p>While <code>nng_cv_wait</code> never fails and so has no return value, the <code>nng_cv_until</code> function can -return <a href="../../api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a> if the time is reached before condition <em>cv</em> is signaled by -either <a href="../../api/synch.html#signaling-the-condition"><code>nng_cv_wake</code></a> or <a href="../../api/synch.html#signaling-the-condition"><code>nng_cv_wake1</code></a>.</p> +return <a href="../api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a> if the time is reached before condition <em>cv</em> is signaled by +either <a href="../api/synch.html#signaling-the-condition"><code>nng_cv_wake</code></a> or <a href="../api/synch.html#signaling-the-condition"><code>nng_cv_wake1</code></a>.</p> <h3 id="signaling-the-condition"><a class="header" href="#signaling-the-condition">Signaling the Condition</a></h3> <pre><code class="language-c">void nng_cv_wake(nng_cv *cv); void nng_cv_wake1(nng_cv *cv); </code></pre> <p>The <a name="a014"></a><code>nng_cv_wake</code> and <a name="a015"></a><code>nng_cv_wake1</code> functions wake threads waiting in -<a href="../../api/synch.html#waiting-for-the-condition"><code>nng_cv_until</code></a> or <a href="../../api/synch.html#waiting-for-the-condition"><code>nng_cv_wait</code></a>. +<a href="../api/synch.html#waiting-for-the-condition"><code>nng_cv_until</code></a> or <a href="../api/synch.html#waiting-for-the-condition"><code>nng_cv_wait</code></a>. The difference between these functions is that <code>nng_cv_wake</code> will wake <em>every</em> thread, whereas <code>nng_cv_wake1</code> will wake up exactly one thread (which may be chosen randomly).</p> @@ -377,9 +377,9 @@ nng_cv_wake(cv); nng_mtx_unlock(m); </code></pre> <h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2> -<p><a href="../../api/thread.html">Threads</a>, -<a href="../../api/time.html">Time</a>, -<a href="../../api/aio.html">Asynchronous I/O</a></p> +<p><a href="../api/thread.html">Threads</a>, +<a href="../api/time.html">Time</a>, +<a href="../api/aio.html">Asynchronous I/O</a></p> <!-- NOTE: This assumes that any page referencing this is located in a directory two levels down. Meaning ./api/somefile.md or similar. mdbook cannot accommodate links that are called from diff --git a/ref/api/thread.html b/ref/api/thread.html index 9c5104e6..83599d30 100644 --- a/ref/api/thread.html +++ b/ref/api/thread.html @@ -279,7 +279,7 @@ Blocking <em>NNG</em> library calls can however be made safely from <em>NNG</em> <p>The system may impose limits on the number of threads that can be created. Typically applications should not create more than a dozen of these. If greater concurrency or scalability is needed, consider instead using -an asynchronous model using <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> structures.</p> +an asynchronous model using <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a> structures.</p> </div> <h2 id="thread-structure"><a class="header" href="#thread-structure">Thread Structure</a></h2> <pre><code class="language-c">typedef struct nng_thread nng_thread; @@ -287,7 +287,7 @@ an asynchronous model using <a href="../../api/aio.html#asynchronous-io-handle"> <p>The <a name="a004"></a><code>nng_thread</code> structure represents a thread, which is a single execution context. A given thread will have its own stack, and CPU registers. However global state, as well as values allocated on the heap, will be shared and accessible to all threads in the system -(See the <a href="../../api/synch.html">Synchronization</a> chapter for functions to help with data sharing between different threads.)</p> +(See the <a href="../api/synch.html">Synchronization</a> chapter for functions to help with data sharing between different threads.)</p> <p>Multiple threads can be thought of as running concurrently, even though they might not actually do so.</p> <p>I/O operations that block (i.e. wait for completion) will block the @@ -314,8 +314,8 @@ It also has the effect of blocking execution in the caller until <em>thr</em> ha to provide a name for the thread. This may change how the thread is represented in debuggers. Not all platforms support setting the thread name.</p> <h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2> -<p><a href="../../api/synch.html">Synchronization</a>, -<a href="../../api/aio.html">Asynchronous Operations</a></p> +<p><a href="../api/synch.html">Synchronization</a>, +<a href="../api/aio.html">Asynchronous Operations</a></p> <!-- NOTE: This assumes that any page referencing this is located in a directory two levels down. Meaning ./api/somefile.md or similar. mdbook cannot accommodate links that are called from diff --git a/ref/api/time.html b/ref/api/time.html index ee901c77..3be2a4e9 100644 --- a/ref/api/time.html +++ b/ref/api/time.html @@ -306,23 +306,23 @@ underlying system.</p> <h2 id="wait-asynchronously"><a class="header" href="#wait-asynchronously">Wait Asynchronously</a></h2> <pre><code class="language-c">void nng_sleep_aio(nng_duration msec, nng_aio *aio); </code></pre> -<p>It is possible to wait as the action on an <a href="../../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, which in effect +<p>It is possible to wait as the action on an <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>, which in effect acts like <a name="a010"></a>scheduling a callback to run after a specified period of time.</p> <p>The <a name="a011"></a><code>nng_sleep_aio</code> function provides this capability. After <em>msec</em> milliseconds have passed, then <em>aio</em>’s callback will be executed. If this sleep waits without interruption, and then completes, the result from -<a href="../../api/aio.html#result-of-operation"><code>nng_aio_result</code></a> will be zero.</p> +<a href="../api/aio.html#result-of-operation"><code>nng_aio_result</code></a> will be zero.</p> <div class="mdbook-alerts mdbook-alerts-note"> <p class="mdbook-alerts-title"> <span class="mdbook-alerts-icon"></span> note </p> -<p>If a timeout shorter than <em>msec</em> is set on <em>aio</em> using <a href="../../api/aio.html#set-timeout"><code>nng_aio_set_timeout</code></a>, -then the sleep will wake up early, with a result code of <a href="../../api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a>.</p> +<p>If a timeout shorter than <em>msec</em> is set on <em>aio</em> using <a href="../api/aio.html#set-timeout"><code>nng_aio_set_timeout</code></a>, +then the sleep will wake up early, with a result code of <a href="../api/errors.html#NNG_ETIMEDOUT"><code>NNG_ETIMEDOUT</code></a>.</p> </div> <h2 id="see-also"><a class="header" href="#see-also">See Also</a></h2> -<p><a href="../../api/aio.html">Asynchronous Operations</a>, -<a href="../../api/synch.html">Synchronization</a></p> +<p><a href="../api/aio.html">Asynchronous Operations</a>, +<a href="../api/synch.html">Synchronization</a></p> <!-- NOTE: This assumes that any page referencing this is located in a directory two levels down. Meaning ./api/somefile.md or similar. mdbook cannot accommodate links that are called from diff --git a/ref/api/url.html b/ref/api/url.html index a38c2a1c..3d448fad 100644 --- a/ref/api/url.html +++ b/ref/api/url.html @@ -293,7 +293,7 @@ the query-information (the part following a ‘?’) and fragment if they are not. The returned string will not include the leading ‘?’ or ‘#’ characters.</p> <p>Note that any strings returned by these functions are only valid until -<em>url</em> is freed with <a href="../../api/url.html#destroy-a-url"><code>nng_url_free</code></a>.</p> +<em>url</em> is freed with <a href="../api/url.html#destroy-a-url"><code>nng_url_free</code></a>.</p> <h2 id="format-a-url"><a class="header" href="#format-a-url">Format a URL</a></h2> <pre><code class="language-c">int nng_url_sprintf(char *buf, size_t bufsz, const nng_url *url); </code></pre> @@ -322,7 +322,7 @@ and creates a dynamically allocated <code>nng_url</code>, returning it in <em>ur <span class="mdbook-alerts-icon"></span> important </p> -<p>Only <a href="../../api/url.html#destroy-a-url"><code>nng_url_free</code></a> should be used to deallocate <code>nng_url</code> objects.</p> +<p>Only <a href="../api/url.html#destroy-a-url"><code>nng_url_free</code></a> should be used to deallocate <code>nng_url</code> objects.</p> </div> <h2 id="clone-a-url"><a class="header" href="#clone-a-url">Clone a URL</a></h2> <pre><code class="language-c">int nng_url_clone(nng_url **dup, const nng_url *url); @@ -332,8 +332,8 @@ and creates a dynamically allocated <code>nng_url</code>, returning it in <em>ur <pre><code class="language-c">void nng_url_free(nng_url *url); </code></pre> <p>The <a name="a013"></a><code>nng_url_free</code> function destroy an <code>nng_url</code> object created with -either <a href="../../api/url.html#parse-a-url"><code>nng_url_parse</code></a> or <a href="../../api/url.html#destroy-a-url"><code>nng_url_free</code></a>.</p> -<p>This is the only correct way to destroy an <a href="../../api/url.html#url-structure"><code>nng_url</code></a> object.</p> +either <a href="../api/url.html#parse-a-url"><code>nng_url_parse</code></a> or <a href="../api/url.html#destroy-a-url"><code>nng_url_free</code></a>.</p> +<p>This is the only correct way to destroy an <a href="../api/url.html#url-structure"><code>nng_url</code></a> object.</p> <h2 id="update-a-url-port"><a class="header" href="#update-a-url-port">Update a URL Port</a></h2> <pre><code class="language-c">void nng_url_resolve_port(nng_url *url, uint32_t port); </code></pre> |
