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.

1 files changed, 10 insertions, 2 deletions

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,