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
207
208
209
210
211
|
/*
* 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 parc_Event.h
* @ingroup events
* @brief Event management
*
* Provides a facade implementing many regularly available event functions.
* This is an interface that software implementors may use to substitute
* different kinds of underlying implementations of these event management functions.
* Notable examples are libevent and libev.
*
*/
#ifndef libparc_parc_Event_h
#define libparc_parc_Event_h
/**
* Current implementation based on top of libevent2
*/
#include <parc/algol/parc_EventScheduler.h>
/**
* @typedef PARCEventType
* @brief An enumeration of event types, with an additional persist flag
*/
typedef enum {
PARCEventType_None = 0x00,
PARCEventType_Timeout = 0x01,
PARCEventType_Read = 0x02,
PARCEventType_Write = 0x04,
PARCEventType_Signal = 0x08,
PARCEventType_Persist = 0x10,
PARCEventType_EdgeTriggered = 0x20
} PARCEventType;
/**
* @typedef PARCEventPriority
* @brief Priority flags for queue scheduling, these currently match the RTA_*_PRIORITY
* this will eventually be replaced.
*/
typedef enum {
PARCEventPriority_Maximum = 0,
PARCEventPriority_Normal = 1,
PARCEventPriority_Minimum = 2,
PARCEventPriority_NumberOfPriorities = 3
} PARCEventPriority;
/**
* @typedef PARCEvent_Callback
* @brief Event callback definition
*/
typedef void (PARCEvent_Callback)(int fileDescriptor, PARCEventType type, void *user_data);
/**
* @typedef PARCEvent
* @brief A structure containing private libevent state data variables
*/
typedef struct PARCEvent PARCEvent;
/**
* Create a new PARCEvent instance.
*
* A new PARCEvent instance is returned.
*
* @param [in] parcEventScheduler base instance
* @param [in] fileDescriptor file descriptor to monitor
* @param [in] events to catch
* @param [in] callback function
* @param [in] callbackArgs function private arguments
* @returns A pointer to the a PARCEvent instance.
*
* Example:
* @code
* static void
* _read_callback(int fileDescriptor, PARCEventType type, void *args)
* {
* }
*
* {
* PARCEventScheduler *eventScheduler = parcEventScheduer_Create();
* PARCEvent *event = parcEvent_Create(eventScheduler, fileDescriptor, PARCEvent_ReadEvent, _read_callback, _read_callback_args);
* }
* @endcode
*
*/
PARCEvent *parcEvent_Create(PARCEventScheduler *parcEventScheduler, int fileDescriptor, PARCEventType events, PARCEvent_Callback *callback, void *callbackArgs);
/**
* Start an event instance.
*
* @param [in] parcEvent instance to start
* @returns -1 on error, 0 on success if nothing changed in the parcEvent backend, and 1 on success if something did.
*
* Example:
* @code
* startEvent(PARCEvent *parcEvent)
* {
* return parcEvent_Start(parcEvent);
* }
* @endcode
*
*/
int parcEvent_Start(PARCEvent *parcEvent);
/**
* Stop a parcEvent instance.
*
* @param [in] parcEvent instance to stop
* @returns -1 on error, 0 on success.
*
* Example:
* @code
* removeEvent(PARCEvent *parcEvent)
* {
* return parcEvent_Stop(parcEvent);
* }
* @endcode
*
*/
int parcEvent_Stop(PARCEvent *parcEvent);
/**
* Poll if an event is available to process
*
* @param [in] parcEvent instance to stop
* @param [in] event type to poll for
* @returns -1 on error, 0 on success.
*
* Example:
* @code
* pollReadEvent(PARCEvent *parcEvent)
* {
* return parcEvent_Poll(parcEvent, PARCEvent_ReadEvent);
* }
* @endcode
*
*/
int parcEvent_Poll(PARCEvent *parcEvent, PARCEventType event);
/**
* Destroy a parcEvent instance.
*
* @param [in] parcEvent address of instance to destroy.
*
* Example:
* @code
* {
* parcEvent_Destroy(&parcEvent);
* }
* @endcode
*
*/
void parcEvent_Destroy(PARCEvent **parcEvent);
/**
* Set a parcEvent instances priority.
*
* @param [in] parcEvent instance to modify
* @param [in] priority to set to
* @returns -1 on error, 0 on success.
*
* Example:
* @code
* {
* return parcEvent_SetPriority(parcEvent, priority);
* }
* @endcode
*
*/
int parcEvent_SetPriority(PARCEvent *parcEvent, PARCEventPriority priority);
/**
* Turn on debugging flags and messages
*
* Example:
* @code
* {
* parcEvent_EnableDebug();
* }
* @endcode
*
*/
void parcEvent_EnableDebug(void);
/**
* Turn off debugging flags and messages
*
* Example:
* @code
* {
* parcEvent_DisableDebug();
* }
* @endcode
*
*/
void parcEvent_DisableDebug(void);
#endif // libparc_parc_Event_h
|
