From 1ad7f88e0c58285c9e1cad9448d5a1fcfa7a07f1 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 26 Dec 2024 14:10:09 -0800 Subject: aio: nng_aio_defer replaced by nng_aio_start This represents an API change, and we remove the nng_aio_begin function as well, introducing the lightweight nng_aio_reset instead. --- docs/ref/api/aio.md | 2 +- docs/ref/migrate/nng1.md | 12 ++++++++++++ docs/ref/xref.md | 4 ++-- 3 files changed, 15 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/api/aio.md b/docs/ref/api/aio.md index 966201ba..6e084e43 100644 --- a/docs/ref/api/aio.md +++ b/docs/ref/api/aio.md @@ -103,7 +103,7 @@ The {{i:`nng_aio_cancel`}} function acts like `nng_aio_abort`, but uses the erro 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`] +new operations scheduled by I/O providers using [`nng_aio_start`] return false. Thus this function should be used to teardown operations. > [!TIP] diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md index 99afb4d3..9e9b6188 100644 --- a/docs/ref/migrate/nng1.md +++ b/docs/ref/migrate/nng1.md @@ -21,6 +21,18 @@ not resubmit an operation that returns it. This is particularly important for ca 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`. +## AIO Provider API changes + +The API used for providers for asynchronous I/O operations has changed slightly. + +- The `nng_aio_begin` function is removed. However a new [`nng_aio_reset`] function should be called + instead, before performing any other operations on an _aio_ object. (This simply clears certain fields.) +- The `nng_aio_defer` function is replaced, with a very [`nng_aio_start`] function. However, this function + has slightly different semantics. It will automatically call the callback if the operation cannot be + scheduled. +- Be aware of the new `NNG_ESTOPPED` error code, for operations on a handle that is being torn down by + the consumer. + ## Transport Specific Functions Transports have not needed to be registered for a long time now, diff --git a/docs/ref/xref.md b/docs/ref/xref.md index d5b7c9f0..8f161de8 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -90,9 +90,9 @@ [`nng_stream_listener_set_tls`]: /TODO.md [`nng_stream_listener_get_tls`]: /TODO.md [`nng_opts_parse`]: /api/cmd_opts.md#parse-command-line-options -[`nng_aio_begin`]: /TODO.md -[`nng_aio_defer`]: /TODO.md [`nng_aio_finish`]: /TODO.md +[`nng_aio_reset`]: /TODO.md +[`nng_aio_start`]: /TODO.md [`nng_aio_set_output`]: /TODO.md [`nng_send`]: /TODO.md [`nng_recv`]: /TODO.md -- cgit v1.2.3-70-g09d2