1 /*
2 * Copyright (c) 2024, The OpenThread Authors.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * 3. Neither the name of the copyright holder nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 /**
30 * @file
31 * This file includes macros for validating runtime conditions.
32 *
33 * The macros in this file should be exclusively used by code under 'lib'. It's RECOMMENDED that only
34 * include this file in sources under 'lib' and not include this file in headers under 'lib'. Because
35 * headers under 'lib' may be included externally and the common macros may cause redefinition.
36 *
37 */
38
39 #ifndef LIB_UTILS_CODE_UTILS_HPP_
40 #define LIB_UTILS_CODE_UTILS_HPP_
41
42 #include <stdbool.h>
43 #include <stddef.h>
44
45 /**
46 * Checks for the specified status, which is expected to commonly be successful, and branches to the local
47 * label 'exit' if the status is unsuccessful.
48 *
49 * @param[in] aStatus A scalar status to be evaluated against zero (0).
50 *
51 */
52 #define EXPECT_NO_ERROR(aStatus) \
53 do \
54 { \
55 if ((aStatus) != 0) \
56 { \
57 goto exit; \
58 } \
59 } while (false)
60
61 /**
62 * Does nothing. This is passed to EXPECT when there is no action to do.
63 *
64 */
65 #define NO_ACTION
66
67 /**
68 * Checks for the specified condition, which is expected to commonly be true, and both executes @a ... and
69 * branches to the local label 'exit' if the condition is false.
70 *
71 * @param[in] aCondition A Boolean expression to be evaluated.
72 * @param[in] aAction An optional expression or block to execute when the assertion fails.
73 *
74 */
75 #define EXPECT(aCondition, aAction) \
76 do \
77 { \
78 if (!(aCondition)) \
79 { \
80 aAction; \
81 goto exit; \
82 } \
83 } while (false)
84
85 /**
86 * Unconditionally executes @a ... and branches to the local label 'exit'.
87 *
88 * @note The use of this interface implies neither success nor failure for the overall exit status of the enclosing
89 * function body.
90 *
91 * @param[in] ... An optional expression or block to execute when the assertion fails.
92 *
93 */
94 #define EXIT_NOW(...) \
95 do \
96 { \
97 __VA_ARGS__; \
98 goto exit; \
99 } while (false)
100
101 /**
102 * Executes the `statement` and ignores the return value.
103 *
104 * This is primarily used to indicate the intention of developer that the return value of a function/method can be
105 * safely ignored.
106 *
107 * @param[in] aStatement The function/method to execute.
108 *
109 */
110 #define IGNORE_RETURN(aStatement) \
111 do \
112 { \
113 if (aStatement) \
114 { \
115 } \
116 } while (false)
117
118 /**
119 * Overload the new operator to new an object at a specific address.
120 *
121 * @param[in] p The pointer of the address.
122 *
123 */
operator new(size_t,void * p)124 inline void *operator new(size_t, void *p) throw() { return p; }
125
126 #endif // LIB_UTILS_CODE_UTILS_HPP_
127
