include/kunit/try-catch.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * An API to allow a function, that may fail, to be executed, and recover in a
0004  * controlled manner.
0005  *
0006  * Copyright (C) 2019, Google LLC.
0007  * Author: Brendan Higgins <brendanhiggins@google.com>
0008  */
0009
0010 #ifndef _KUNIT_TRY_CATCH_H
0011 #define _KUNIT_TRY_CATCH_H
0012
0013 #include <linux/types.h>
0014
0015 typedef void (*kunit_try_catch_func_t)(void *);
0016
0017 struct completion;
0018 struct kunit;
0019
0020 /**
0021  * struct kunit_try_catch - provides a generic way to run code which might fail.
0022  * @test: The test case that is currently being executed.
0023  * @try_completion: Completion that the control thread waits on while test runs.
0024  * @try_result: Contains any errno obtained while running test case.
0025  * @try: The function, the test case, to attempt to run.
0026  * @catch: The function called if @try bails out.
0027  * @context: used to pass user data to the try and catch functions.
0028  *
0029  * kunit_try_catch provides a generic, architecture independent way to execute
0030  * an arbitrary function of type kunit_try_catch_func_t which may bail out by
0031  * calling kunit_try_catch_throw(). If kunit_try_catch_throw() is called, @try
0032  * is stopped at the site of invocation and @catch is called.
0033  *
0034  * struct kunit_try_catch provides a generic interface for the functionality
0035  * needed to implement kunit->abort() which in turn is needed for implementing
0036  * assertions. Assertions allow stating a precondition for a test simplifying
0037  * how test cases are written and presented.
0038  *
0039  * Assertions are like expectations, except they abort (call
0040  * kunit_try_catch_throw()) when the specified condition is not met. This is
0041  * useful when you look at a test case as a logical statement about some piece
0042  * of code, where assertions are the premises for the test case, and the
0043  * conclusion is a set of predicates, rather expectations, that must all be
0044  * true. If your premises are violated, it does not makes sense to continue.
0045  */
0046 struct kunit_try_catch {
0047     /* private: internal use only. */
0048     struct kunit *test;
0049     struct completion *try_completion;
0050     int try_result;
0051     kunit_try_catch_func_t try;
0052     kunit_try_catch_func_t catch;
0053     void *context;
0054 };
0055
0056 void kunit_try_catch_run(struct kunit_try_catch *try_catch, void *context);
0057
0058 void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch);
0059
0060 static inline int kunit_try_catch_get_result(struct kunit_try_catch *try_catch)
0061 {
0062     return try_catch->try_result;
0063 }
0064
0065 #endif /* _KUNIT_TRY_CATCH_H */