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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
/*
* Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
* Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
* Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
*
* This software is available to you under a choice of one of two
* licenses. You may choose to be licensed under the terms of the GNU
* General Public License (GPL) Version 2, available from the file
* COPYING in the main directory of this source tree, or the
* OpenIB.org BSD license below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
*/
/*
* Abstract:
* Declaration of event abstraction.
*/
#ifndef _CL_EVENT_H_
#define _CL_EVENT_H_
/* Indicates that waiting on an event should never timeout */
#define EVENT_NO_TIMEOUT 0xFFFFFFFF
#include <complib/cl_event_osd.h>
#ifdef __cplusplus
# define BEGIN_C_DECLS extern "C" {
# define END_C_DECLS }
#else /* !__cplusplus */
# define BEGIN_C_DECLS
# define END_C_DECLS
#endif /* __cplusplus */
BEGIN_C_DECLS
/****h* Component Library/Event
* NAME
* Event
*
* DESCRIPTION
* The Event provides the ability to suspend and wakeup a thread.
*
* The event functions operates on a cl_event_t structure which should be
* treated as opaque and should be manipulated only through the provided
* functions.
*
* SEE ALSO
* Structures:
* cl_event_t
*
* Initialization/Destruction:
* cl_event_construct, cl_event_init, cl_event_destroy
*
* Manipulation:
* cl_event_signal, cl_event_reset, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_construct
* NAME
* cl_event_construct
*
* DESCRIPTION
* The cl_event_construct function constructs an event.
*
* SYNOPSIS
*/
void cl_event_construct(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to construct.
*
* RETURN VALUE
* This function does not return a value.
*
* NOTES
* Allows calling cl_event_destroy without first calling cl_event_init.
*
* Calling cl_event_construct is a prerequisite to calling any other event
* function except cl_event_init.
*
* SEE ALSO
* Event, cl_event_init, cl_event_destroy
*********/
/****f* Component Library: Event/cl_event_init
* NAME
* cl_event_init
*
* DESCRIPTION
* The cl_event_init function initializes an event for use.
*
* SYNOPSIS
*/
cl_status_t
cl_event_init(IN cl_event_t * const p_event, IN const boolean_t manual_reset);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to initialize.
*
* manual_reset
* [in] If FALSE, indicates that the event resets itself after releasing
* a single waiter. If TRUE, the event remains in the signalled state
* until explicitly reset by a call to cl_event_reset.
*
* RETURN VALUES
* CL_SUCCESS if event initialization succeeded.
*
* CL_ERROR otherwise.
*
* NOTES
* Allows calling event manipulation functions, such as cl_event_signal,
* cl_event_reset, and cl_event_wait_on.
*
* The event is initially in a reset state.
*
* SEE ALSO
* Event, cl_event_construct, cl_event_destroy, cl_event_signal,
* cl_event_reset, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_destroy
* NAME
* cl_event_destroy
*
* DESCRIPTION
* The cl_event_destroy function performs any necessary cleanup of an event.
*
* SYNOPSIS
*/
void cl_event_destroy(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to destroy.
*
* RETURN VALUE
* This function does not return a value.
*
* NOTES
* This function should only be called after a call to cl_event_construct
* or cl_event_init.
*
* SEE ALSO
* Event, cl_event_construct, cl_event_init
*********/
/****f* Component Library: Event/cl_event_signal
* NAME
* cl_event_signal
*
* DESCRIPTION
* The cl_event_signal function sets an event to the signalled state and
* releases at most one waiting thread.
*
* SYNOPSIS
*/
cl_status_t cl_event_signal(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to set.
*
* RETURN VALUES
* CL_SUCCESS if the event was successfully signalled.
*
* CL_ERROR otherwise.
*
* NOTES
* For auto-reset events, the event is reset automatically once a wait
* operation is satisfied.
*
* Triggering the event multiple times does not guarantee that the same
* number of wait operations are satisfied. This is because events are
* either in a signalled on non-signalled state, and triggering an event
* that is already in the signalled state has no effect.
*
* SEE ALSO
* Event, cl_event_reset, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_reset
* NAME
* cl_event_reset
*
* DESCRIPTION
* The cl_event_reset function sets an event to the non-signalled state.
*
* SYNOPSIS
*/
cl_status_t cl_event_reset(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to reset.
*
* RETURN VALUES
* CL_SUCCESS if the event was successfully reset.
*
* CL_ERROR otherwise.
*
* SEE ALSO
* Event, cl_event_signal, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_wait_on
* NAME
* cl_event_wait_on
*
* DESCRIPTION
* The cl_event_wait_on function waits for the specified event to be
* triggered for a minimum amount of time.
*
* SYNOPSIS
*/
cl_status_t
cl_event_wait_on(IN cl_event_t * const p_event,
IN const uint32_t wait_us, IN const boolean_t interruptible);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure on which to wait.
*
* wait_us
* [in] Number of microseconds to wait.
*
* interruptible
* [in] Indicates whether the wait operation can be interrupted
* by external signals.
*
* RETURN VALUES
* CL_SUCCESS if the wait operation succeeded in response to the event
* being set.
*
* CL_TIMEOUT if the specified time period elapses.
*
* CL_NOT_DONE if the wait was interrupted by an external signal.
*
* CL_ERROR if the wait operation failed.
*
* NOTES
* If wait_us is set to EVENT_NO_TIMEOUT, the function will wait until the
* event is triggered and never timeout.
*
* If the timeout value is zero, this function simply tests the state of
* the event.
*
* If the event is already on the signalled state at the time of the call
* to cl_event_wait_on, the call completes immediately with CL_SUCCESS.
*
* SEE ALSO
* Event, cl_event_signal, cl_event_reset
*********/
END_C_DECLS
#endif /* _CL_EVENT_H_ */
|
