3
A brief file description
5
@section license License
7
Licensed to the Apache Software Foundation (ASF) under one
8
or more contributor license agreements. See the NOTICE file
9
distributed with this work for additional information
10
regarding copyright ownership. The ASF licenses this file
11
to you under the Apache License, Version 2.0 (the
12
"License"); you may not use this file except in compliance
13
with the License. You may obtain a copy of the License at
15
http://www.apache.org/licenses/LICENSE-2.0
17
Unless required by applicable law or agreed to in writing, software
18
distributed under the License is distributed on an "AS IS" BASIS,
19
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20
See the License for the specific language governing permissions and
21
limitations under the License.
24
#ifndef _I_EventProcessor_h_
25
#define _I_EventProcessor_h_
28
#include "I_Continuation.h"
29
#include "I_Processor.h"
32
const int MAX_THREADS_IN_EACH_TYPE = 512;
33
const int MAX_EVENT_THREADS = 512;
38
Main processor for the Event System. The EventProcessor is the core
39
component of the Event System. Once started, it is responsible for
40
creating and managing groups of threads that execute user-defined
41
tasks asynchronously at a given time or periodically.
43
The EventProcessor provides a set of scheduling functions through
44
which you can specify continuations to be called back by one of its
45
threads. These function calls do not block. Instead they return an
46
Event object and schedule the callback to the continuation passed in at
47
a later or specific time, as soon as possible or at certain intervals.
51
Every executable that imports and statically links against the
52
EventSystem library is provided with a global instance of the
53
EventProcessor called eventProcessor. Therefore, it is not necessary to
54
create instances of the EventProcessor class because it was designed
55
as a singleton. It is important to note that none of its functions
58
Thread Groups (Event types):
60
When the EventProcessor is started, the first group of threads is
61
spawned and it is assigned the special id ET_CALL. Depending on the
62
complexity of the state machine or protocol, you may be interested
63
in creating additional threads and the EventProcessor gives you the
64
ability to create a single thread or an entire group of threads. In
65
the former case, you call spawn_thread and the thread is independent
66
of the thread groups and it exists as long as your continuation handle
67
executes and there are events to process. In the latter, you call
68
spawn_event_theads which creates a new thread group and you get an id
69
or event type with wich you must keep for use later on when scheduling
70
continuations on that group.
74
@b UNIX: For all of the scheduling functions, the callback_event
75
parameter is not used. On a callback, the event code passed in to
76
the continuation handler is always EVENT_IMMEDIATE.
78
@b NT: The value of the event code passed in to the continuation
79
handler is the value provided in the callback_event parameter.
81
Event allocation policy:
83
Events are allocated and deallocated by the EventProcessor. A state
84
machine may access the returned, non-recurring event until it is
85
cancelled or the callback from the event is complete. For recurring
86
events, the Event may be accessed until it is cancelled. Once the event
87
is complete or cancelled, it's the eventProcessor's responsibility to
91
class EventProcessor:public Processor
96
Spawn an additional thread for calling back the continuation. Spawns
97
a dedicated thread (EThread) that calls back the continuation passed
98
in as soon as possible.
100
@param cont continuation that the spawn thread will call back
102
@param sem Unix: Event semaphore assigned to the thread. NT: Not used.
103
@return event object representing the start of the thread.
106
Event * spawn_thread(Continuation * cont, ink_sem * sem = NULL);
109
Spawns a group of threads for an event type. Spawns the number of
110
event threads passed in (n_threads) creating a thread group and
111
returns the thread group id (or EventType). See the remarks section
114
@return EventType or thread id for the new group of threads.
117
EventType spawn_event_threads(int n_threads);
121
Schedules the continuation on a specific EThread to receive an event
122
at the given timeout. Requests the EventProcessor to schedule
123
the callback to the continuation 'c' at the time specified in
124
'atimeout_at'. The event is assigned to the specified EThread.
126
@param c Continuation to be called back at the time specified in
128
@param atimeout_at time value at which to callback.
129
@param ethread EThread on which to schedule the event.
130
@param callback_event code to be passed back to the continuation's
131
handler. See the Remarks section.
132
@param cookie user-defined value or pointer to be passed back in
133
the Event's object cookie field.
134
@return reference to an Event object representing the scheduling
138
Event *schedule_imm(Continuation * c,
139
EventType event_type = ET_CALL, int callback_event = EVENT_IMMEDIATE, void *cookie = NULL);
141
provides the same functionality as schedule_imm and also signals the thread immediately
143
Event *schedule_imm_signal(Continuation * c,
144
EventType event_type = ET_CALL, int callback_event = EVENT_IMMEDIATE, void *cookie = NULL);
146
Schedules the continuation on a specific thread group to receive an
147
event at the given timeout. Requests the EventProcessor to schedule
148
the callback to the continuation 'c' at the time specified in
149
'atimeout_at'. The callback is handled by a thread in the specified
150
thread group (event_type).
152
@param c Continuation to be called back at the time specified in
154
@param atimeout_at Time value at which to callback.
155
@param event_type thread group id (or event type) specifying the
156
group of threads on which to schedule the callback.
157
@param callback_event code to be passed back to the continuation's
158
handler. See the Remarks section.
159
@param cookie user-defined value or pointer to be passed back in
160
the Event's object cookie field.
161
@return reference to an Event object representing the scheduling of
165
Event *schedule_at(Continuation * c,
166
ink_hrtime atimeout_at,
167
EventType event_type = ET_CALL, int callback_event = EVENT_INTERVAL, void *cookie = NULL);
170
Schedules the continuation on a specific thread group to receive an
171
event after the specified timeout elapses. Requests the EventProcessor
172
to schedule the callback to the continuation 'c' after the time
173
specified in 'atimeout_in' elapses. The callback is handled by a
174
thread in the specified thread group (event_type).
176
@param c Continuation to call back aftert the timeout elapses.
177
@param atimeout_in amount of time after which to callback.
178
@param event_type Thread group id (or event type) specifying the
179
group of threads on which to schedule the callback.
180
@param callback_event code to be passed back to the continuation's
181
handler. See the Remarks section.
182
@param cookie user-defined value or pointer to be passed back in
183
the Event's object cookie field.
184
@return reference to an Event object representing the scheduling of
188
Event *schedule_in(Continuation * c,
189
ink_hrtime atimeout_in,
190
EventType event_type = ET_CALL, int callback_event = EVENT_INTERVAL, void *cookie = NULL);
193
Schedules the continuation on a specific thread group to receive
194
an event periodically. Requests the EventProcessor to schedule the
195
callback to the continuation 'c' everytime 'aperiod' elapses. The
196
callback is handled by a thread in the specified thread group
199
@param c Continuation to call back everytime 'aperiod' elapses.
200
@param aperiod duration of the time period between callbacks.
201
@param event_type thread group id (or event type) specifying the
202
group of threads on which to schedule the callback.
203
@param callback_event code to be passed back to the continuation's
204
handler. See the Remarks section.
205
@param cookie user-defined value or pointer to be passed back in
206
the Event's object cookie field.
207
@return reference to an Event object representing the scheduling of
211
Event *schedule_every(Continuation * c,
213
EventType event_type = ET_CALL, int callback_event = EVENT_INTERVAL, void *cookie = NULL);
216
////////////////////////////////////////////
217
// reschedule an already scheduled event. //
218
// may be called directly or called by //
219
// schedule_xxx Event member functions. //
220
// The returned value may be different //
221
// from the argument e. //
222
////////////////////////////////////////////
224
Event *reschedule_imm(Event * e, int callback_event = EVENT_IMMEDIATE);
225
Event *reschedule_at(Event * e, ink_hrtime atimeout_at, int callback_event = EVENT_INTERVAL);
226
Event *reschedule_in(Event * e, ink_hrtime atimeout_in, int callback_event = EVENT_INTERVAL);
227
Event *reschedule_every(Event * e, ink_hrtime aperiod, int callback_event = EVENT_INTERVAL);
232
Initializes the EventProcessor and its associated threads. Spawns the
233
specified number of threads, initializes their state information and
234
sets them running. It creates the initial thread group, represented
235
by the event type ET_CALL.
237
@return 0 if successful, and a negative value otherwise.
240
int start(int n_net_threads);
243
Stop the EventProcessor. Attempts to stop the EventProcessor and
244
all of the threads in each of the thread groups.
247
virtual void shutdown();
250
Allocates size bytes on the event threads. This function is thread
253
@param size bytes to be allocated.
256
off_t allocate(int size);
259
An array of pointers to all of the EThreads handled by the
260
EventProcessor. An array of pointers to all of the EThreads created
261
throughout the existence of the EventProcessor instance.
264
EThread *all_ethreads[MAX_EVENT_THREADS];
267
An array of pointers, organized by thread group, to all of the
268
EThreads handled by the EventProcessor. An array of pointers to all of
269
the EThreads created throughout the existence of the EventProcessor
270
instance. It is a two-dimensional array whose first dimension is the
271
thread group id and the second the EThread pointers for that group.
274
EThread *eventthread[MAX_EVENT_TYPES][MAX_THREADS_IN_EACH_TYPE];
276
unsigned int next_thread_for_type[MAX_EVENT_TYPES];
277
int n_threads_for_type[MAX_EVENT_TYPES];
280
Total number of threads controlled by this EventProcessor. This is
281
the count of all the EThreads spawn by this EventProcessor, excluding
282
those created by spawn_thread
288
Total number of thread groups created so far. This is the count of
289
all the thread groups (event types) created for this EventProcessor.
295
// prevent unauthorized copies (Not implemented)
296
EventProcessor(const EventProcessor &);
297
EventProcessor & operator =(const EventProcessor &);
301
/*------------------------------------------------------*\
302
| Unix & non NT Interface |
303
\*------------------------------------------------------*/
305
Event * schedule(Event * e, EventType etype, bool fast_signal = false);
306
EThread *assign_thread(EventType etype);
308
EThread *dthreads[MAX_EVENT_THREADS];
309
int n_dthreads; // No. of dedicated threads
310
volatile int thread_data_used;
313
extern inkcoreapi class EventProcessor eventProcessor;
315
#endif /*_EventProcessor_h_*/
added
removed
iocore/eventsystem/I_EventProcessor.h
