aio: introduce NNG_ESTOPPED

This error code results when an AIO is stopped permanently, as a result
of nni_aio_close or nni_aio_stop.  The associated AIO object cannot be
used again.  This discrimantes against a file being closed, or a temporary
cancellation which might allow the aio to be reused.

Consumers must check for this error status in their callbacks, and not
resubmit an operation that failed with this error.  Doing so, will result
in an infinite loop of submit / errors.

3 files changed, 12 insertions, 3 deletions

diff --git a/docs/ref/api/aio.md b/docs/ref/api/aio.md
index 230744e8..966201ba 100644
--- a/docs/ref/api/aio.md
+++ b/docs/ref/api/aio.md
@@ -100,7 +100,7 @@ then [`nng_aio_result`] will return _err_.
 The {{i:`nng_aio_cancel`}} function acts like `nng_aio_abort`, but uses the error code
 [`NNG_ECANCELED`]{{hi:`NNG_ECANCELED`}}.
 
-The {{i:`nng_aio_stop`}} function aborts the _aio_ operation with [`NNG_ECANCELED`],
+The {{i:`nng_aio_stop`}} function aborts the _aio_ operation with [`NNG_ESTOPPED`],
 and then waits the operation and any associated callback to complete.
 This function also marks _aio_ itself permanently stopped, so that any
 new operations scheduled by I/O providers using [`nng_aio_begin`]
diff --git a/docs/ref/api/errors.md b/docs/ref/api/errors.md
index 6548c263..6954b658 100644
--- a/docs/ref/api/errors.md
+++ b/docs/ref/api/errors.md
@@ -69,6 +69,7 @@ future locale-specific strings may be presented instead.
 | `NNG_EAMBIGUOUS`<a name="NNG_EAMBIGUOUS"></a>     | 29                      | Ambiguous option. The command line option could not be unambiguously resolved. Only used with [`nng_opts_parse`].                                 |
 | `NNG_EBADTYPE`<a name="NNG_EBADTYPE"></a>         | 30                      | Incorrect type. A type-specific function was used for an object of the wrong type.                                                                |
 | `NNG_ECONNSHUT`<a name="NNG_ECONNSHUT"></a>       | 31                      | Connection shutdown. The connection was shut down and cannot be used.                                                                             |
+| `NNG_ESTOPPED`<a name="NNG_ESTOPPED"></a>         | 1000                    | Operation stopped. The operation was stopped with [`nng_aio_stop`] or [`nng_aio_close`].                                                          |
 | `NNG_EINTERNAL`<a name="NNG_EINTERNAL"></a>       | 1000                    | An unidentifier internal error occurred.                                                                                                          |
 | `NNG_ESYSERR`<a name="NNG_ESYSERR"></a>           | 0x10000000 - 0x1FFFFFFF | An unidentified system error occurred. These are errors reported by the operating system.                                                         |
 | `NNG_ETRANERR`<a name="NNG_ETRANERR"></a>         | 0x20000000 - 0x2FFFFFFF | An unidentified transport error occurred.                                                                                                         |
diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md
index 0d6ae86d..99afb4d3 100644
--- a/docs/ref/migrate/nng1.md
+++ b/docs/ref/migrate/nng1.md
@@ -1,7 +1,7 @@
 # Migrating from NNG 1.x
 
-There are some incompatibities from NNG 1.x.
-This guide should help in migrating applications to use NNG 2.0.
+There are some incompatibities from NNG 1.x, and applications must make certain changes for NNG 2.0.
+This guide should help with this migration.
 
 ## Nanomsg Compatibility
 
@@ -13,6 +13,14 @@ See the [Migrating From libnanomsg](nanomsg.md) chapter for details.
 It is now required for applications to initialize the library explicitly before using it.
 This is done using the [`nng_init`] function.
 
+## New AIO Error Code NNG_ESTOPPED
+
+When an operation fails with [`NNG_ESTOPPED`], it means that the associated [`nni_aio`] object has
+been permanently stopped and must not be reused. Applications must watch for this error code, and
+not resubmit an operation that returns it. This is particularly important for callbacks that automatically
+resubmit operations. Failure to observe this rule will lead to an infinite loop
+as any further operations on the object will fail immediately with `NNG_ESTOPPED`.
+
 ## Transport Specific Functions
 
 Transports have not needed to be registered for a long time now,