From c72bd53e2c5b4bc7207bfa1710ccff47655a099a Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 20 Aug 2018 11:09:23 -0700 Subject: fixes #506 AIO "providers" need a way to call nni_aio_schedule. --- docs/man/CMakeLists.txt | 2 + docs/man/libnng.3.adoc | 4 +- docs/man/nng_aio_begin.3.adoc | 64 ++++++++++++++++++++++++ docs/man/nng_aio_defer.3.adoc | 78 ++++++++++++++++++++++++++++++ docs/man/nng_aio_finish.3.adoc | 2 + docs/man/nng_http_handler_alloc.3http.adoc | 11 ++++- src/nng.c | 15 ++++++ src/nng.h | 18 +++++++ tests/aio.c | 20 ++++++++ 9 files changed, 212 insertions(+), 2 deletions(-) create mode 100644 docs/man/nng_aio_begin.3.adoc create mode 100644 docs/man/nng_aio_defer.3.adoc diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index 726d95c4..af644a62 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -62,8 +62,10 @@ if (NNG_ENABLE_DOC) libnng nng_aio_abort nng_aio_alloc + nng_aio_begin nng_aio_cancel nng_aio_count + nng_aio_defer nng_aio_finish nng_aio_free nng_aio_get_input diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index ec88cdd0..23306997 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -152,9 +152,11 @@ The following functions are used in the asynchronous model: |=== |<>|abort asynchronous I/O operation |<>|allocate asynchronous I/O handle +|<>|begin asynchronous I/O operation |<>|cancel asynchronous I/O operation |<>|return number of bytes transferred -|<>|finish an asynchronous I/O operation +|<>|defer asynchronous I/O operation +|<>|finish asynchronous I/O operation |<>|free asynchronous I/O handle |<>|return input parameter |<>|get message from an asynchronous receive diff --git a/docs/man/nng_aio_begin.3.adoc b/docs/man/nng_aio_begin.3.adoc new file mode 100644 index 00000000..fd72d401 --- /dev/null +++ b/docs/man/nng_aio_begin.3.adoc @@ -0,0 +1,64 @@ += nng_aio_begin(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_begin - begin asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +bool nng_aio_begin(nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_aio_begin()` function is called by the I/O provider to indicate that +it is going to process the operation. + +The function may return `false`, indicating that the _aio_ has been closed +by the caller asynchronously. +In this case the provider should abandon the operation and do nothing else. + +This operation should be called at the start of any I/O operation, and must +be called not more than once for a given I/O operation on a given _aio_. + +Once this function is called, if `true` is returned, then the provider MUST +guarantee that `<>` is called for the _aio_ +exactly once, when the operation is complete or canceled. + +NOTE: This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the _aio_ should not call this function. + +== RETURN VALUES + +[horizontal] +`true`:: The operation has been started. +`false`:: The operation cannot be started. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_aio_defer.3.adoc b/docs/man/nng_aio_defer.3.adoc new file mode 100644 index 00000000..67520293 --- /dev/null +++ b/docs/man/nng_aio_defer.3.adoc @@ -0,0 +1,78 @@ += nng_aio_defer(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_aio_defer - defer asynchronous I/O operation + +== SYNOPSIS + +[source, c] +---- +#include + +typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err); + +void nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg); +---- + +== DESCRIPTION + +The `nng_aio_defer()` function marks operation associated with _aio_ as +being deferred for asynchronous completion, and also registers a cancellation +function _fn_ and associated argument _arg_, thereby +permitting the operation to be canceled. + +If the _aio_ is being canceled, the cancellation routine _fn_ will be called +with the _aio_, the _arg_ specified by `nng_aio_defer()`, and an error +value in _err_, which is the reason that the operation is being canceled. + +The operation may not be cancelable; for example it may have already been +completed, or be in a state where it is no longer possible to unschedule it. +In this case, the _cancelfn_ should just return without making any changes. + +If the cancellation routine successfully canceled the operation, it should +ensure that `<>` is called, with the +error code specified by _err_. + +IMPORTANT: It is mandatory that I/O providers call +`<>` +*EXACTLY ONCE* when they are finished with the operation. + +NOTE: This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the _aio_ should not call this function. + +NOTE: Care must be taken to ensure that cancellation and completion of +the routine are multi-thread safe; this will usually involve the use +of locks or other synchronization primitives. + +TIP: For operations that complete synchronously, without any need to be +deferred, the provider should not bother to call `nng_aio_defer()`, +although it is harmless if it does. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_aio_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc index 00148fd6..4733c1f2 100644 --- a/docs/man/nng_aio_finish.3.adoc +++ b/docs/man/nng_aio_finish.3.adoc @@ -52,7 +52,9 @@ None. [.text-left] <>, +<>, <>, +<>, <>, <>, <> diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc index 187b91b6..523b5328 100644 --- a/docs/man/nng_http_handler_alloc.3http.adoc +++ b/docs/man/nng_http_handler_alloc.3http.adoc @@ -63,7 +63,8 @@ The generic (first) form of this creates a handler that uses a user-supplied function to process HTTP requests. This function uses the asynchronous I/O framework. The function takes a pointer to an `<>` structure. -That structure will be passed with the following input values (retrieved with + +The _aio_ will be passed with the following input values (retrieved with `<>`): 0: `nng_http_req *` __request__:: The client's HTTP request. @@ -86,6 +87,13 @@ If any non-zero status is returned back to the caller instead, then a generic 500 response will be created and sent, if possible, and the connection will be closed. +The _aio_ may be scheduled for deferred completion using the +`<>` function. + +NOTE: The callback function should *NOT* call +`<>`, +as that will already have been done by the server framework. + === Directory Handler The second member of this family, `nng_http_handler_alloc_directory()`, creates @@ -137,6 +145,7 @@ This function returns 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] +<>, <>, <>, <>, diff --git a/src/nng.c b/src/nng.c index f7f16954..37ee3e5f 100644 --- a/src/nng.c +++ b/src/nng.c @@ -1601,6 +1601,21 @@ nng_aio_finish(nng_aio *aio, int rv) nni_aio_finish(aio, rv, nni_aio_count(aio)); } +void +nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg) +{ + nni_aio_schedule(aio, fn, arg); +} + +bool +nng_aio_begin(nng_aio *aio) +{ + if (nni_aio_begin(aio) != 0) { + return (false); + } + return (true); +} + #if 0 int nng_snapshot_create(nng_socket sock, nng_snapshot **snapp) diff --git a/src/nng.h b/src/nng.h index 50e557a4..6bc38c90 100644 --- a/src/nng.h +++ b/src/nng.h @@ -564,6 +564,11 @@ NNG_DECL void nng_aio_set_timeout(nng_aio *, nng_duration); // to succeed if n <= 4, otherwise it may fail due to NNG_ENOMEM. NNG_DECL int nng_aio_set_iov(nng_aio *, unsigned, const nng_iov *); +// nng_aio_begin is called by the provider to mark the operation as +// beginning. If it returns false, then the provider must take no +// further action on the aio. +NNG_DECL bool nng_aio_begin(nng_aio *); + // nng_aio_finish is used to "finish" an asynchronous operation. // It should only be called by "providers" (such as HTTP server API users). // The argument is the value that nng_aio_result() should return. @@ -571,6 +576,19 @@ NNG_DECL int nng_aio_set_iov(nng_aio *, unsigned, const nng_iov *); // given aio. NNG_DECL void nng_aio_finish(nng_aio *, int); +// nng_aio_defer is used to register a cancellation routine, and indicate +// that the operation will be completed asynchronously. It must only be +// called once per operation on an aio, and must only be called by providers. +// If the operation is canceled by the consumer, the cancellation callback +// will be called. The provider *must* still ensure that the nng_aio_finish() +// function is called EXACTLY ONCE. If the operation cannot be canceled +// for any reason, the cancellation callback should do nothing. The +// final argument is passed to the cancelfn. The final argument of the +// cancellation function is the error number (will not be zero) corresponding +// to the reason for cancellation, e.g. NNG_ETIMEDOUT or NNG_ECANCELED. +typedef void (*nng_aio_cancelfn)(nng_aio *, void *, int); +NNG_DECL void nng_aio_defer(nng_aio *, nng_aio_cancelfn, void *); + // nng_aio_sleep does a "sleeping" operation, basically does nothing // but wait for the specified number of milliseconds to expire, then // calls the callback. This returns 0, rather than NNG_ETIMEDOUT. diff --git a/tests/aio.c b/tests/aio.c index bd5c5097..0efc013a 100644 --- a/tests/aio.c +++ b/tests/aio.c @@ -35,6 +35,13 @@ sleepdone(void *arg) *(nng_time *) arg = nng_clock(); } +void +cancelfn(nng_aio *aio, void *arg, int rv) +{ + *(int *) arg = rv; + nng_aio_finish(aio, rv); +} + Main({ Test("AIO operations", { const char *addr = "inproc://aio"; @@ -179,6 +186,19 @@ Main({ So(nng_aio_set_iov(aio, 1024, &iov) == NNG_EINVAL); nng_aio_free(aio); }); + + Convey("Provider cancellation works", { + nng_aio *aio; + int rv = 0; + // We fake an empty provider that does not do anything. + So(nng_aio_alloc(&aio, NULL, NULL) == 0); + So(nng_aio_begin(aio) == true); + nng_aio_defer(aio, cancelfn, &rv); + nng_aio_cancel(aio); + nng_aio_wait(aio); + So(rv == NNG_ECANCELED); + nng_aio_free(aio); + }); }); nng_fini(); -- cgit v1.2.3-70-g09d2