From df3fe33ff4e075220868c3afb6fa2d4ab0daa68e Mon Sep 17 00:00:00 2001 From: paul Luse Date: Thu, 1 Jul 2021 17:58:22 +0000 Subject: [PATCH] thread.h: document expected poller return values. Code isn't alway consistent (for legacy reasons) so lets at least document what we expect moving forward. Signed-off-by: paul Luse Change-Id: Iba9e383ae89ec9f850dcacca45c3bf8410c3b28b Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/8582 Community-CI: Mellanox Build Bot Tested-by: SPDK CI Jenkins Reviewed-by: Aleksey Marchuk Reviewed-by: Jim Harris --- include/spdk/thread.h | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/include/spdk/thread.h b/include/spdk/thread.h index c602b6ec01..f0f59a28bc 100644 --- a/include/spdk/thread.h +++ b/include/spdk/thread.h @@ -45,6 +45,10 @@ extern "C" { #endif +/** + * Pollers should always return a value of this type + * indicating whether they did real work or not. + */ enum spdk_thread_poller_rc { SPDK_POLLER_IDLE, SPDK_POLLER_BUSY, @@ -117,9 +121,8 @@ typedef void (*spdk_thread_pass_msg)(spdk_msg_fn fn, void *ctx, * Callback function for a poller. * * \param ctx Context passed as arg to spdk_poller_register(). - * \return 0 to indicate that polling took place but no events were found; - * positive to indicate that polling took place and some events were processed; - * negative if the poller does not provide spin-wait information. + * \return value of type `enum spdk_thread_poller_rc` (ex: SPDK_POLLER_IDLE + * if no work was done or SPDK_POLLER_BUSY if work was done.) */ typedef int (*spdk_poller_fn)(void *ctx); @@ -561,7 +564,9 @@ struct spdk_poller *spdk_poller_register_named(spdk_poller_fn fn, /* * \brief Register a poller on the current thread with setting its name - * to the string of the poller function name. + * to the string of the poller function name. The poller being registered + * should return a value of type `enum spdk_thread_poller_rc`. See + * \ref spdk_poller_fn for more information. */ #define SPDK_POLLER_REGISTER(fn, arg, period_microseconds) \ spdk_poller_register_named(fn, arg, period_microseconds, #fn)