diff options
Diffstat (limited to 'longbow/src/LongBow/longBow_Runtime.h')
| -rw-r--r-- | longbow/src/LongBow/longBow_Runtime.h | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/longbow/src/LongBow/longBow_Runtime.h b/longbow/src/LongBow/longBow_Runtime.h new file mode 100644 index 00000000..ff5527eb --- /dev/null +++ b/longbow/src/LongBow/longBow_Runtime.h @@ -0,0 +1,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 |