1 files changed, 101 insertions, 4 deletions
diff --git a/ref/api/aio.html b/ref/api/aio.html
index 796c6a51..fa4dcdbf 100644
--- a/ref/api/aio.html
+++ b/ref/api/aio.html
@@ -336,7 +336,7 @@ then <a href="../api/aio.html#result-of-operation"><code>nng_aio_result</code></
 <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="../api/aio.html#starting-an-operation"><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">
@@ -465,17 +465,29 @@ start an attempt to complete any partial transfer, check the amount of data tran
 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);
+<pre><code class="language-c">void *nng_aio_get_input(nng_aio *aio, unsigned int index);
 void *nng_aio_get_output(nng_aio *aio, unsigned int index);
+void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
+void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result);
 </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>
 <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>
-for the operation associated with <em>aio</em>.</p>
+<p>The <code>nng_aio_set_output</code> function sets the output result at <em>index</em>
+to <em>result</em> for the operation associated with <em>aio</em>.</p>
+<p>The <code>nng_aio_get_output</code> function returns the output result previously set by <code>nng_aio_set_output</code>.</p>
+<p>The <code>nng_aio_get_input</code> function returns the input parameter previously set by <code>nng_aio_set_input</code>.</p>
 <p>The type and semantics of input parameters and output results are determined by specific
 operations. The documentation for the operation should provide details.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Most applications will not need to use <code>nng_aio_get_input</code> or <code>nng_aio_set_output</code>, as those
+are used by <a href="../api/aio.html#io-providers">I/O Providers</a>.</p>
+</div>
 <p>The valid values of <em>index</em> range from zero (0) to three (3), as no operation
 currently defined can accept more than four parameters or return more than four additional
 results.</p>
@@ -517,6 +529,91 @@ 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>,
 and if necessary resubmit the operation with a suitably updated vector of <code>nng_iov</code> using this function.</p>
+<h2 id="io-providers"><a class="header" href="#io-providers">I/O Providers</a></h2>
+<p>This section documents functions that are used by I/O providers, and will not be relevant
+for the majority of applications that simply utilize operations provided for by the library.</p>
+<p>However, these functions will be useful if an application wants to implement its own asynchronous operations using <a href="../api/aio.html#asynchronous-io-handle"><code>nng_aio</code></a>.</p>
+<h3 id="starting-an-operation"><a class="header" href="#starting-an-operation">Starting an Operation</a></h3>
+<pre><code class="language-c">typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, nng_err err);
+
+void nng_aio_reset(nng_aio *aio);
+bool nng_aio_start(nng_aio *aio, nng_aio_cancelfn fn, void *arg);
+</code></pre>
+<p>The <a name="a026"></a><code>nng_aio_reset</code> function resets various fields in the <em>aio</em>.
+It can be called before starting an operation.</p>
+<p>The <a name="a027"></a><code>nng_aio_start</code> function starts the operation associated with <em>aio</em>.
+It implies the same reset as <code>nng_aio_reset</code>. Thus, <code>nng_aio_reset</code> is typically
+only useful when used with operations that complete synchronously.
+The <code>nng_aio_start</code> function also registers the cancellation function <em>fn</em> and
+associated argument <em>arg</em> with the operation. This allows the operation to be canceled.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>This function must not be called on an <em>aio</em> that is already has an operation in progress.</p>
+</div>
+<p>If <em>fn</em> is <code>NULL</code>, then the operation cannot be canceled.</p>
+<p>If <code>nng_aio_start</code> returns <code>false</code>, then the <em>aio</em> has been permanently stopped
+and the operation cannot proceed. In this case the caller should cease all
+work with <em>aio</em>, and must not call <a href="../api/aio.html#finishing-an-operation"><code>nng_aio_finish</code></a> or any other function,
+as the <em>aio</em> is no longer valid for use.</p>
+<p>If <code>nng_aio_start</code> returns true, then the operation may proceed.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>Failure to check the return value from <code>nng_aio_start</code> can lead to deadlocks
+or infinite loops.</p>
+</div>
+<p>If the <em>aio</em> is subsequently canceled, the cancellation routine <em>fn</em> will be called
+with <em>aio</em> and <em>arg</em> and an error value in <em>err</em>.
+The <em>err</em> indicates the reason that the operation is being canceled.</p>
+<p>If the operation cannot be canceled, <em>fn</em> should just return without making any change.</p>
+<p>If <em>fn</em> successfully canceled the operation, it should
+ensure that <a href="../api/aio.html#finishing-an-operation"><code>nng_aio_finish</code></a> is called with the error code specified by <em>err</em>.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>It is mandatory that I/O providers call <a href="../api/aio.html#finishing-an-operation"><code>nng_aio_finish</code></a>
+<em>exactly once</em> when they are finished with the operation.</p>
+</div>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Ensure that cancellation and completion of the routine are thread safe.
+This usually involves the use of locks or other synchronization primitives.</p>
+</div>
+<h3 id="finishing-an-operation"><a class="header" href="#finishing-an-operation">Finishing an Operation</a></h3>
+<pre><code class="language-c">void nng_aio_finish(nng_aio *aio, nng_err err);
+</code></pre>
+<p>The <a name="a028"></a><code>nng_aio_finish</code> function completes the operation associated with <em>aio</em>.
+The result of the the status <em>err</em>.</p>
+<p>This function causes the callback associated with the <em>aio</em> to called.
+The <em>aio</em> may not be referenced again by the caller.</p>
+<div class="mdbook-alerts mdbook-alerts-tip">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  tip
+</p>
+<p>Set any results using <a href="../api/aio.html#inputs-and-outputs"><code>nng_aio_set_output</code></a> before calling this function.</p>
+</div>
+<p>The return value subsequently obtained from <a href="../api/aio.html#result-of-operation"><code>nng_aio_result</code></a> for <em>aio</em> will be <em>err</em>.</p>
+<div class="mdbook-alerts mdbook-alerts-important">
+<p class="mdbook-alerts-title">
+  <span class="mdbook-alerts-icon"></span>
+  important
+</p>
+<p>It is mandatory that operation providers call this function
+<em>exactly once</em> when they are finished with the operation.
+After calling this function they <em>must not</em> perform any further accesses
+to the <em>aio</em>.</p>
+</div>
 <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>,