include/kunit/try-catch.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * An API to allow a function, that may fail, to be executed, and recover in a
   4  * controlled manner.
   5  *
   6  * Copyright (C) 2019, Google LLC.
   7  * Author: Brendan Higgins <brendanhiggins@google.com>
   8  */
   9
  10 #ifndef _KUNIT_TRY_CATCH_H
  11 #define _KUNIT_TRY_CATCH_H
  12
  13 #include <linux/types.h>
  14
  15 typedef void (*kunit_try_catch_func_t)(void *);
  16
  17 struct completion;
  18 struct kunit;
  19
  20 /**
  21  * struct kunit_try_catch - provides a generic way to run code which might fail.
  22  * @test: The test case that is currently being executed.
  23  * @try_completion: Completion that the control thread waits on while test runs.
  24  * @try_result: Contains any errno obtained while running test case.
  25  * @try: The function, the test case, to attempt to run.
  26  * @catch: The function called if @try bails out.
  27  * @context: used to pass user data to the try and catch functions.
  28  *
  29  * kunit_try_catch provides a generic, architecture independent way to execute
  30  * an arbitrary function of type kunit_try_catch_func_t which may bail out by
  31  * calling kunit_try_catch_throw(). If kunit_try_catch_throw() is called, @try
  32  * is stopped at the site of invocation and @catch is called.
  33  *
  34  * struct kunit_try_catch provides a generic interface for the functionality
  35  * needed to implement kunit->abort() which in turn is needed for implementing
  36  * assertions. Assertions allow stating a precondition for a test simplifying
  37  * how test cases are written and presented.
  38  *
  39  * Assertions are like expectations, except they abort (call
  40  * kunit_try_catch_throw()) when the specified condition is not met. This is
  41  * useful when you look at a test case as a logical statement about some piece
  42  * of code, where assertions are the premises for the test case, and the
  43  * conclusion is a set of predicates, rather expectations, that must all be
  44  * true. If your premises are violated, it does not makes sense to continue.
  45  */
  46 struct kunit_try_catch {
  47         /* private: internal use only. */
  48         struct kunit *test;
  49         struct completion *try_completion;
  50         int try_result;
  51         kunit_try_catch_func_t try;
  52         kunit_try_catch_func_t catch;
  53         void *context;
  54 };
  55
  56 void kunit_try_catch_init(struct kunit_try_catch *try_catch,
  57                           struct kunit *test,
  58                           kunit_try_catch_func_t try,
  59                           kunit_try_catch_func_t catch);
  60
  61 void kunit_try_catch_run(struct kunit_try_catch *try_catch, void *context);
  62
  63 void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch);
  64
  65 static inline int kunit_try_catch_get_result(struct kunit_try_catch *try_catch)
  66 {
  67         return try_catch->try_result;
  68 }
  69
  70 /*
  71  * Exposed for testing only.
  72  */
  73 void kunit_generic_try_catch_init(struct kunit_try_catch *try_catch);
  74
  75 #endif /* _KUNIT_TRY_CATCH_H */