On 3/25/23 06:31, David Gow wrote:
Many uses of the KUnit resource system are intended to simply defer
calling a function until the test exits (be it due to success or
failure). The existing kunit_alloc_resource() function is often used for
this, but was awkward to use (requiring passing NULL init functions, etc),
and returned a resource without incrementing its reference count, which
-- while okay for this use-case -- could cause problems in others.
Instead, introduce a simple kunit_defer() API: a simple function
(returning nothing, accepting a single void* argument) can be scheduled
to be called when the test exits. Deferred functions are called in the
opposite order to that which they were registered.
This is implemented as a resource under the hood, so the ordering
between resource cleanup and deferred functions is maintained.
Signed-off-by: David Gow <davidgow@xxxxxxxxxx>
---
include/kunit/resource.h | 87 +++++++++++++++++++++++++++++++
lib/kunit/resource.c | 110 +++++++++++++++++++++++++++++++++++++++
2 files changed, 197 insertions(+)
diff --git a/include/kunit/resource.h b/include/kunit/resource.h
index cf6fb8f2ac1b..6c4728ca9237 100644
--- a/include/kunit/resource.h
+++ b/include/kunit/resource.h
@@ -387,4 +387,91 @@ static inline int kunit_destroy_named_resource(struct kunit *test,
*/
void kunit_remove_resource(struct kunit *test, struct kunit_resource *res);
+typedef void (*kunit_defer_function_t)(void *ctx);
+
+/**
+ * kunit_defer() - Defer a function call until the test ends.
+ * @test: Test case to associate the deferred function with.
+ * @func: The function to run on test exit
+ * @ctx: Data passed into @func
+ * @internal_gfp: gfp to use for internal allocations, if unsure, use GFP_KERNEL
+ *
+ * Defer the execution of a function until the test exits, either normally or
+ * due to a failure. @ctx is passed as additional context. All functions
+ * registered with kunit_defer() will execute in the opposite order to that
+ * they were registered in.
+ *
+ * This is useful for cleaning up allocated memory and resources.
+ *
+ * RETURNS:
Is this intentional? Unless I'm mistaken the kernel-doc return value
specifier is 'Return:'.
+ * An opaque "cancellation token", or NULL on error. Pass this token to
+ * kunit_defer_cancel() in order to cancel the deferred execution of func().
+ */
+void *kunit_defer(struct kunit *test, kunit_defer_function_t func,
+ void *ctx, gfp_t internal_gfp);
+
+/**
+ * kunit_defer_cancel_token() - Cancel a deferred function call.
+ * @test: Test case the deferred function is associated with.
+ * @cancel_token: The cancellation token returned by kunit_defer()
+ *
+ * Prevent a function deferred using kunit_defer() from executing when the
+ * test ends.
+ *
+ * Prefer using this to kunit_defer_cancel() where possible.
+ */
+void kunit_defer_cancel_token(struct kunit *test, void *cancel_token);
+
+/**
+ * kunit_defer_trigger_token() - Run a deferred function call immediately.
+ * @test: Test case the deferred function is associated with.
+ * @cancel_token: The cancellation token returned by kunit_defer()
+ *
+ * Execute a deferred function call immediately, instead of waiting for the
+ * test to end.
+ *
+ * Prefer using this to kunit_defer_trigger() where possible.
+ */
+void kunit_defer_trigger_token(struct kunit *test, void *cancel_token);
+
+/**
+ * kunit_defer_cancel() - Cancel a matching deferred function call.
+ * @test: Test case the deferred function is associated with.
+ * @func: The deferred function to cancel.
+ * @ctx: The context passed to the deferred function to trigger.
+ *
+ * Prevent a function deferred via kunit_defer() from executing at shutdown.
+ * Unlike kunit_defer_cancel_token(), this takes the (func, ctx) pair instead of
+ * the cancellation token. If that function/context pair was deferred multiple
+ * times, only the most recent one will be cancelled.
+ *
+ * Prefer using kunit_defer_cancel_token() to this where possible.
+ */
+void kunit_defer_cancel(struct kunit *test,
+ kunit_defer_function_t func,
+ void *ctx);
+
+/**
+ * kunit_defer_trigger() - Run a matching deferred function call immediately.
+ * @test: Test case the deferred function is associated with.
+ * @func: The deferred function to trigger.
+ * @ctx: The context passed to the deferred function to trigger.
+ *
+ * Execute a function deferred via kunit_defer() immediately, rather than when
+ * the test ends.
+ * Unlike kunit_defer_trigger_token(), this takes the (func, ctx) pair instead of
+ * the cancellation token. If that function/context pair was deferred multiple
+ * times, it will only be executed once here. The most recent deferral will
+ * no longer execute when the test ends.
+ *
+ * kunit_defer_trigger(test, func, ctx);
+ * is equivalent to
+ * func(ctx);
+ * kunit_defer_cancel(test, func, ctx);
+ *
+ * Prefer using kunit_defer_trigger_token() to this where possible.
+ */
+void kunit_defer_trigger(struct kunit *test,
+ kunit_defer_function_t func,
+ void *ctx);
#endif /* _KUNIT_RESOURCE_H */
diff --git a/lib/kunit/resource.c b/lib/kunit/resource.c
index c414df922f34..0d0c48054d45 100644
--- a/lib/kunit/resource.c
+++ b/lib/kunit/resource.c
@@ -77,3 +77,113 @@ int kunit_destroy_resource(struct kunit *test, kunit_resource_match_t match,
return 0;
}
EXPORT_SYMBOL_GPL(kunit_destroy_resource);
+
+struct kunit_defer_ctx {
+ kunit_defer_function_t func;
+ void *ctx;
+};
+
+static void __kunit_defer_free(struct kunit_resource *res)
+{
+ struct kunit_defer_ctx *defer_ctx = (struct kunit_defer_ctx *)res->data;
+
+ defer_ctx->func(defer_ctx->ctx);
+
+ kfree(res->data);
+}
+
+void *kunit_defer(struct kunit *test, kunit_defer_function_t func,
+ void *ctx, gfp_t internal_gfp)
+{
+ struct kunit_resource *res;
+ struct kunit_defer_ctx *defer_ctx;
+
+ KUNIT_ASSERT_NOT_NULL_MSG(test, func, "Tried to defer a NULL function!");
+
+ res = kzalloc(sizeof(*res), internal_gfp);
+ if (!res)
+ return NULL;
+
+ defer_ctx = kzalloc(sizeof(*defer_ctx), internal_gfp);
+ if (!defer_ctx)
+ goto free_res;
+
+ defer_ctx->func = func;
+ defer_ctx->ctx = ctx;
+
+ res->should_kfree = true;
+ __kunit_add_resource(test, NULL, __kunit_defer_free, res, defer_ctx);
+
+ return (void *)res;
+
+free_res:
+ kfree(res);
+ return NULL;
+}
+
+void kunit_defer_cancel_token(struct kunit *test, void *cancel_token)
+{
+ struct kunit_resource *res = (struct kunit_resource *)cancel_token;
+
+ /* Remove the free function so we don't run the deferred function. */
+ res->free = NULL;
+
+ kunit_remove_resource(test, res);
+}
+
+void kunit_defer_trigger_token(struct kunit *test, void *cancel_token)
+{
+ struct kunit_resource *res = (struct kunit_resource *)cancel_token;
+
+ /* Removing the resource should trigger the res->free function. */
+ kunit_remove_resource(test, res);
+}
+
+static bool __kunit_defer_match(struct kunit *test,
+ struct kunit_resource *res, void *match_data)
+{
+ struct kunit_defer_ctx *match_ctx = (struct kunit_defer_ctx *)match_data;
+ struct kunit_defer_ctx *res_ctx = (struct kunit_defer_ctx *)res->data;
+
+ /* Make sure this is a free function. */
+ if (res->free != __kunit_defer_free)
+ return false;
+
+ /* Both the function and context data should match. */
+ return (match_ctx->func == res_ctx->func) && (match_ctx->ctx == res_ctx->ctx);
+}
+
+void kunit_defer_cancel(struct kunit *test,
+ kunit_defer_function_t func,
+ void *ctx)
+{
+ struct kunit_defer_ctx defer_ctx;
+ struct kunit_resource *res;
+
+ defer_ctx.func = func;
+ defer_ctx.ctx = ctx;
+
+ res = kunit_find_resource(test, __kunit_defer_match, &defer_ctx);
+ if (res) {
+ kunit_defer_cancel_token(test, res);
+ kunit_put_resource(res);
+ }
+}
+
+void kunit_defer_trigger(struct kunit *test,
+ kunit_defer_function_t func,
+ void *ctx)
+{
+ struct kunit_defer_ctx defer_ctx;
+ struct kunit_resource *res;
+
+ defer_ctx.func = func;
+ defer_ctx.ctx = ctx;
+
+ res = kunit_find_resource(test, __kunit_defer_match, &defer_ctx);
+ if (res) {
+ kunit_defer_trigger_token(test, res);
+ /* We have to put() this here, else free won't be called. */
+ kunit_put_resource(res);
+ }
+}
I am not really sure if you must provide the 'tokenless' cancel or
trigger APIs. They just feel a bit much to me. Well, if you have a
reason to do so then this looks good to me.
Yours,
-- Matti
--
Matti Vaittinen
Linux kernel developer at ROHM Semiconductors
Oulu Finland
~~ When things go utterly wrong vim users can always type :help! ~~
