1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
/*
* Copyright (c) 2017 Cisco and/or its affiliates.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @file longBow_Runtime.h
* @ingroup runtime
* @brief The LongBow Runtime support.
*
*/
#ifndef LongBow_longBow_Runtime_h
#define LongBow_longBow_Runtime_h
#include <LongBow/longBow_Event.h>
#include <LongBow/longBow_RuntimeResult.h>
#include <LongBow/longBow_Config.h>
struct longbow_runtime;
typedef struct longbow_runtime LongBowRuntime;
/**
* Create and return a new `LongBowRuntime` instance with the specified `LongBowRuntimeResult` instance.
*
* @param [in] expectedResultTemplate A `LongBowRuntimeResult` instance.
*
* @return A pointer to an allocated LongBowRuntime instance that must be deallocated via longBowRuntime_Destroy
*/
LongBowRuntime *longBowRuntime_Create(const LongBowRuntimeResult *expectedResultTemplate, LongBowConfig *config);
/**
* Destroy the `LongBowRuntime` instance.
*
* @param [in,out] runtimePtr A pointer to a `LongBowRuntime` instance.
*/
void longBowRuntime_Destroy(LongBowRuntime **runtimePtr);
/**
* Get the expected test case result from the `LongBowRuntime` instance.
*
* @param [in] runtime A `LongBowRuntime` instance.
*
* @return A pointer to the expected LongBowRuntimeResult.
*/
LongBowRuntimeResult *longBowRuntime_GetExpectedTestCaseResult(const LongBowRuntime *runtime);
/**
* Get the actual test case result from the `LongBowRuntime` instance.
*
* @param [in] runtime A `LongBowRuntime` instance.
*
* @return A pointer to the actual LongBowRuntimeResult.
*/
LongBowRuntimeResult *longBowRuntime_GetActualTestCaseResult(const LongBowRuntime *runtime);
/**
* Get the number of events that were evalutated.
*
* @param [in] runtime A `LongBowRuntime` instance.
*
* @return The number of events that were evalutated.
*/
size_t longBowRuntime_GetActualEventEvaluationCount(LongBowRuntime *runtime);
/**
* Get the LongBowEventType of the given LongBowRuntime.
*
* @param [in] runtime A `LongBowRuntime` instance.
*
* @return The LongBowEventType of the given LongBowRuntime.
*/
LongBowEventType *longBowRuntime_GetActualEventType(const LongBowRuntime *runtime);
/**
* Get the expected EventType from the given LongBowRuntime.
*
* When testing, a test may set a LongBowEventType that is expected to be triggered.
* This function simply gets the expected LongBowEventType from the given LongBowRuntime instance.
*
* @param [in] runtime A pointer to a LongBowRuntime instance.
*
* @return The expected EventType in the LongBowRuntime.
*/
LongBowEventType *longBowRuntime_GetExpectedEventType(const LongBowRuntime *runtime);
/**
* Set the "actual" LongBowEventType of the given LongBowRuntime.
*
* @param [in] runtime A `LongBowRuntime` instance.
* @param [in] eventType A `LongBowEventType` instance.
*/
void longBowRuntime_SetActualEventType(LongBowRuntime *runtime, LongBowEventType *eventType);
/**
* Set the current `LongBowRuntime`.
*
* @param [in] runtime A `LongBowRuntime` instance.
*
* @return The previous LongBowRuntime
*/
LongBowRuntime *longBowRuntime_SetCurrentRuntime(LongBowRuntime *runtime);
/**
* Retrieve the current `LongBowRuntime`.
*
* @return The current global LongBowRuntime.
*/
LongBowRuntime *longBowRuntime_GetCurrentRuntime(void);
/**
* Retrieve the `LongBowConfig` instance of the current global runtime.
*
* @return The `LongBowConfig` instance of the current global runtime.
*/
LongBowConfig *longBowRuntime_GetCurrentConfig(void);
/**
* Set the `LongBowConfig` instance of the current global runtime.
*
* @param [in] config The new `LongBowConfig` instance of the current global runtime.
*/
void longBowRuntime_SetCurrentConfig(LongBowConfig *config);
/**
* Trigger a LongBow event.
*
* The event will be reported via the longBowReport_Event.
*
* @param [in] eventType The type of event.
* @param [in] location The LongBowLocation of the event (this will be destroyed).
* @param [in] kind A string indicating the kind of event this is triggering.
* @param [in] format A printf format string.
* @param [in] ... Parameters associated with the printf format string.
*
* @return true Always return true.
*/
bool longBowRuntime_EventTrigger(LongBowEventType *eventType,
LongBowLocation *location,
const char *kind,
const char *format, ...) __attribute__((__format__(__printf__, 4, 5)));
/**
* Record an event evaluation.
*
* This only records the fact of the evaluation, not the results of the evaluation.
*
* @param [in] type A pointer to the LongBowEventType being evaluated.
*
* @return true Always returns true.
*
* Example:
* @code
* {
* longBowRuntime_EventEvaluation(&LongBowAssertEvent);
* }
* @endcode
*/
bool longBowRuntime_EventEvaluation(const LongBowEventType *type);
/**
* Set the current value for the depth of printed stack trace.
*
* If the depth is less than 1, no stack trace is displayed.
*
* @param [in] newDepth The new value to set.
*
* @return The previous value.
*/
unsigned int longBowRuntime_SetStackTraceDepth(unsigned int newDepth);
/**
* Get the current value for the depth of printed stack trace.
*
* @return The current stack-trace depth.
*/
unsigned int longBowRuntime_GetStackTraceDepth(void);
/**
* Print a formatted stack trace to the current output file descriptor.
*
* @param [in] fileDescriptor A valid file descriptor.
*/
void longBowRuntime_StackTrace(int fileDescriptor);
/**
* Abort the running process using the current runtime environment.
* If the configuration is set to produce a core dump, this function simply returns.
* This permits the caller to use the form:
* <code>
* longBowRuntime_Abort(), kill(0, SIGTRACE)
* </code>
* To generate a core image.
*
* See the assertion macros for how this is used.
*/
void longBowRuntime_Abort(void);
#endif // LongBow_longBow_Runtime_h
|
