blob: 12f903c073003f53b385a5255cfebba1c09c88f7 (
plain)
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
|
/*
* 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_Event.h
* @ingroup internals
* @brief LongBow Event Support.
*
* LongBow assertions, traps and tests induce "events" which are experienced by the programme runtime as signals or long-jumps.
*
*/
#ifndef LongBow_longBow_Event_h
#define LongBow_longBow_Event_h
#include <stdlib.h>
#include <stdbool.h>
#include <LongBow/longBow_EventType.h>
#include <LongBow/longBow_Location.h>
#include <LongBow/longBow_Backtrace.h>
struct longbow_event;
/**
* @typedef LongBowEvent
*/
typedef struct longbow_event LongBowEvent;
/**
* Get the `LongBowEventType` of a LongBowEvent.
*
* @param [in] event A `LongBowEvent` instance.
*
* @return A pointer to the LongBowEventType of the event.
*
* Example:
* @code
* {
* LongBowEvent *event = ...
* LongBowEventType type = longBowEvent_GetEventType(event);
* }
* @endcode
*/
const LongBowEventType *longBowEvent_GetEventType(const LongBowEvent *event);
/**
* Create a `LongBowEvent`.
*
* Creating a `LongBowEvent` records runtime data and used by report facilities.
* This does not actually cause the process to assert the assertion.
*
* @param [in] eventType The LongBowEventType for this event.
* @param [in] location A LongBowLocation instance recording the location of the event.
* @param [in] kind A string representing the kind of event.
* @param [in] message A message to display. This will be freed via free(3).
* @param [in] backtrace A pointer to a valid LongBowBacktrace instance.
*
* @return An allocated LongBowEvent which must be destroyed via `longBowEvent_Destroy()`.
*/
LongBowEvent *longBowEvent_Create(const LongBowEventType *eventType, const LongBowLocation *location, const char *kind, const char *message, const LongBowBacktrace *backtrace);
/**
* Destroy a `LongBowEvent`.
*
* The value pointed to by `eventPtr`, is set to `NULL.
*
* @param [in,out] eventPtr The `LongBowEvent` instance to destroy and NULLify.
*/
void longBowEvent_Destroy(LongBowEvent **eventPtr);
/**
* Get the `LongBowLocation` associated with this `LongBowEvent` instance.
*
* @param [in] event A `LongBowEvent` instance.
*
* @return A pointer to the `LongBowLocation` instance for the given `LongBowEvent`.
*/
const LongBowLocation *longBowEvent_GetLocation(const LongBowEvent *event);
/**
* Get the name.
*
* @param [in] event A `LongBowEvent` instance.
*
* @return The name of the given LongBowEvent.
*/
const char *longBowEvent_GetName(const LongBowEvent *event);
/**
* Get a pointer to the string representing the kind of this event.
*
* Currently the kind is only a static string set when creating a `LongBowEvent`.
*
* @param [in] event A pointer to a `LongBowEvent` instance.
*
* @return non-NULL The pointer to the string representing the kind of this event.
* @return NULL The kind was not set.
*
* @see longBowEvent_Create
*/
const char *longBowEvent_GetKind(const LongBowEvent *event);
/**
* Retrieve the message associated with this `LongBowEvent` instance.
*
* @param [in] event A `LongBowEvent` instance.
*
* @return The message associated with the given `LongBowEvent`.
*/
const char *longBowEvent_GetMessage(const LongBowEvent *event);
/**
* Get the `LongBowBacktrace` instance for the given `LongBowEvent` instance.
*
* @param [in] event A pointer to a valid LongBowEvent instance.
*
* @return A pointer to a LongBowBacktrace instance.
*/
const LongBowBacktrace *longBowEvent_GetBacktrace(const LongBowEvent *event);
/**
* Get an array of nul-terminated C strings containing the symbolic representation of the given `LongBowEvent` stack backtrace.
* The length of the array is provided by `longBowEvent_GetCallStackLength`
*
* @param [in] event A pointer to a valid `LongBowEvent` instance.
*
* @return non-NULL An array of nul-terminated C strings
* @see longBowEvent_GetCallStackLength
*/
char **longBowEvent_CreateSymbolicCallstack(const LongBowEvent *event);
/**
* Retrieve the call stack length associated with this `LongBowEvent` instance.
*
* @param [in] event A `LongBowEvent` instance.
*
* @return The length of the call stack.
*/
size_t longBowEvent_GetCallStackLength(const LongBowEvent *event);
#endif // LongBow_longBow_Event_h
|
