LXR linux/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
  15typedef void (*kunit_try_catch_func_t)(void *);
  16
  17struct completion;
  18struct 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 */
  46struct 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
  56void kunit_try_catch_run(struct kunit_try_catch *try_catch, void *context);
  57
  58void __noreturn kunit_try_catch_throw(struct kunit_try_catch *try_catch);
  59
  60static inline int kunit_try_catch_get_result(struct kunit_try_catch *try_catch)
  61{
  62        return try_catch->try_result;
  63}
  64
  65#endif /* _KUNIT_TRY_CATCH_H */
  66