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 <[email protected]>
   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 kunit;
  18
  19 /**
  20  * struct kunit_try_catch - provides a generic way to run code which might fail.
  21  * @test: The test case that is currently being executed.
  22  * @try_result: Contains any errno obtained while running test case.
  23  * @try: The function, the test case, to attempt to run.
  24  * @catch: The function called if @try bails out.
  25  * @context: used to pass user data to the try and catch functions.
  26  *
  27  * kunit_try_catch provides a generic, architecture independent way to execute
  28  * an arbitrary function of type kunit_try_catch_func_t which may bail out by
  29  * calling kunit_try_catch_throw(). If kunit_try_catch_throw() is called, @try
  30  * is stopped at the site of invocation and @catch is called.
  31  *
  32  * struct kunit_try_catch provides a generic interface for the functionality
  33  * needed to implement kunit->abort() which in turn is needed for implementing
  34  * assertions. Assertions allow stating a precondition for a test simplifying
  35  * how test cases are written and presented.
  36  *
  37  * Assertions are like expectations, except they abort (call
  38  * kunit_try_catch_throw()) when the specified condition is not met. This is
  39  * useful when you look at a test case as a logical statement about some piece
  40  * of code, where assertions are the premises for the test case, and the
  41  * conclusion is a set of predicates, rather expectations, that must all be
  42  * true. If your premises are violated, it does not makes sense to continue.
  43  */
  44 struct kunit_try_catch {
  45         /* private: internal use only. */
  46         struct kunit *test;
  47         int try_result;
  48         kunit_try_catch_func_t try;
  49         kunit_try_catch_func_t catch;
  50         void *context;
  51 };
  52
  53 void kunit_try_catch_run(struct kunit_try_catch *try_catch, void *context);
  54
  55 void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch);
  56
  57 static inline int kunit_try_catch_get_result(struct kunit_try_catch *try_catch)
  58 {
  59         return try_catch->try_result;
  60 }
  61
  62 #endif /* _KUNIT_TRY_CATCH_H */