Skip to content
Newer
Older
100644 385 lines (300 sloc) 12.5 KB
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
1 include::license.txt[]
2
3 :language: C
4
5 Creating an event_base
6 ----------------------
7
8 Before you can use any interesting Libevent function, you need to allocate
9 one or more event_base structures. Each event_base structure holds a set of
85b35f1 Initial editing pass from Susan.
@ authored
10 events and can poll to determine which events are active.
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
11
12 If an event_base is set up to use locking, it is safe to access it between
13 multiple threads. Its loop can only be run in a single thread, however. If
14 you want to have multiple threads polling for IO, you need to have an
15 event_base for each thread.
16
17 TIP: [A future version of Libevent may have support for event_bases that run
18 events across multiple threads.]
19
20 Each event_base has a "method", or a backend that it uses to determine which
21 events are ready. The recognized methods are:
22
23 - select
24 - poll
25 - epoll
26 - kqueue
27 - devpoll
28 - evport
29 - win32
30
31 The user can disable specific backends with environment variables. If you
32 want to turn off the kqueue backend, set the EVENT_NOKQUEUE environment
33 variable, and so on. If you want to turn off backends from within the
34 program, see notes on event_config_avoid_method() below.
35
36 Setting up a default event_base
37 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38
39 The event_base_new() function allocates and returns a new event base with
85b35f1 Initial editing pass from Susan.
@ authored
40 the default settings. It examines the environment variables and returns
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
41 a pointer to a new event_base. If there is an error, it returns NULL.
42
43 When choosing among methods, it picks the fastest method that the OS
44 supports.
45
46 .Interface
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
47 [code,C]
48 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
49 struct event_base *event_base_new(void);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
50 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
51
52 For most programs, this is all you need.
53
54 The event_base_new() function is declared in <event2/event.h>. It first
55 appeared in Libevent 1.4.3.
56
57 Setting up a complicated event_base
58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60 If you want more control over what kind of event_base you get, you need to
61 use an event_config. An event_config is an opaque structure that holds
62 information about your preferences for an event_base. When you want an
63 event_base, you pass the event_config to event_base_new_with_config().
64
65 .Interface
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
66 [code,C]
67 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
68 struct event_config *event_config_new(void);
0b1e73a Note a few functions that just got const-ized
Nick Mathewson authored
69 struct event_base *event_base_new_with_config(const struct event_config *cfg);
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
70 void event_config_free(struct event_config *cfg);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
71 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
72
73 To allocate an event_base with these functions, you call event_config_new()
74 to allocate a new event_config. Then, you call other functions on the
75 event_config to tell it about your needs. Finally, you call
76 event_base_new_with_config() to get a new event_base. When you are done,
77 you can free the event_config with event_config_free().
78
79 .Interface
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
80 [code,C]
81 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
82 int event_config_avoid_method(struct event_config *cfg, const char *method);
83
84 enum event_method_feature {
85 EV_FEATURE_ET = 0x01,
86 EV_FEATURE_O1 = 0x02,
87 EV_FEATURE_FDS = 0x04,
88 };
89 int event_config_require_features(struct event_config *cfg,
90 enum event_method_feature feature);
91
92 enum event_base_config_flag {
fa74aaa Revise sections up to Ref5 for 2.0.3-alpha.
Nick Mathewson authored
93 EVENT_BASE_FLAG_NOLOCK = 0x01,
94 EVENT_BASE_FLAG_IGNORE_ENV = 0x02,
95 EVENT_BASE_FLAG_STARTUP_IOCP = 0x04,
96 EVENT_BASE_FLAG_NO_CACHE_TIME = 0x08,
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
97 };
98 int event_config_set_flag(struct event_config *cfg,
99 enum event_base_config_flag flag);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
100 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
101
85b35f1 Initial editing pass from Susan.
@ authored
102 Calling event_config_avoid_method tells Libevent to avoid a specific
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
103 available backend by name. Calling event_config_require_feature() tells
104 Libevent not to use any backend that cannot supply all of a set of features.
fa74aaa Revise sections up to Ref5 for 2.0.3-alpha.
Nick Mathewson authored
105 Calling event_config_set_flag() tells Libevent to set one or more of
106 the run-time flags below when constructing the event base.
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
107
108 The recognized feature values for event_config_require_features are:
109
110 - EV_FEATURE_ET: Requires a backend method that supports edge-triggered IO.
111 - EV_FEATURE_O1: Requires a backend method where adding or deleting a single
112 event, or having a single event become active, is an O(1) operation.
113 - EV_FEATURE_FDS: Requires a backend method that can support arbitrary file
114 descriptor types, and not just sockets.
115
116 The recognized option values for event_config_set_flag() are:
117
118 - EVENT_BASE_FLAG_NOLOCK: Do not allocate locks for the event_base. Setting
119 this option may save a little time for locking and releasing the
120 event_base, but will make it unsafe to access it from multiple threads.
121 - EVENT_BASE_FLAG_IGNORE_ENV: Do not check the EVENT_NO* environment
122 variables when picking which backend method to use. Think hard before
123 using this flag: it can make it harder for users to debug the interactions
124 between your program and Libevent.
fa74aaa Revise sections up to Ref5 for 2.0.3-alpha.
Nick Mathewson authored
125 - EVENT_BASE_FLAG_STARTUP_IOCP: On Window only, this flag makes Libevent
126 enable any necessary IOCP dispatch logic on startup, rather than
127 on-demand.
128 - EVENT_BASE_FLAG_NO_CACHE_TIME: Instead of checking the current time every
129 time the event loop is ready to run timeout callbacks, check it after
130 every timeout callback. This can use more CPU than you necessarily
131 intended, so watch out!
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
132
133 The above functions that manipulate an event_config all return 0 on success,
134 -1 on failure.
135
3f42620 @shahn typo cleanup
shahn authored
136 NOTE: It is easy to set up an event_config that requires a backend that your
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
137 OS does not provide. For example, as of Libevent 2.0.1-alpha, there is no
138 O(1) backend for Windows, and no backend on Linux that provides both
139 EV_FEATURE_FDS and EV_FEATURE_O1. If you have made a configuration that
140 Libevent can't satisfy, event_base_new_with_config() will return NULL.
141
53babe0 Make all examples compile correctly
Nick Mathewson authored
142
143 //BUILD: FUNCTIONBODY INC:event2/event.h
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
144 .Example
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
145 [code,C]
146 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
147 struct event_config *cfg;
53babe0 Make all examples compile correctly
Nick Mathewson authored
148 struct event_base *base;
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
149 int i;
150
151 /* My program wants to use edge-triggered events if at all possible. So
152 I'll try to get a base twice: Once insisting on edge-triggered IO, and
153 once not. */
154 for (i=0; i<2; ++i) {
155 cfg = event_config_new();
156
157 /* I don't like select. */
158 event_config_avoid_method(cfg, "select");
159
160 if (i == 0)
161 event_config_require_features(cfg, EV_FEATURE_ET);
162
163 base = event_base_new_with_config(cfg);
164 event_config_free(cfg);
165 if (base)
166 break;
167
168 /* If we get here, event_base_new_with_config() returned NULL. If
169 this is the first time around the loop, we'll try again without
170 setting EV_FEATURE_ET. If this is the second time around the
171 loop, we'll give up. */
172 }
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
173 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
174
175 These functions and types are declared in <event2/event.h>.
176
177 The EVENT_BASE_FLAG_IGNORE_ENV flag first appeared in Libevent 2.0.2-alpha.
178 Everything else in this section first appeared in Libevent 2.0.1-alpha.
179
180 Examining an event_base's backend method
181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182
183 Sometimes you want to see which features are actually available in an
184 event_base, or which method it's using.
185
186 .Interface
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
187 [code,C]
188 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
189 const char **event_get_supported_methods(void);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
190 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
191
192 The event_get_supported_methods() function returns a pointer to an array of
193 the names of the methods supported in this version of Libevent. The
194 last element in the array is NULL.
195
53babe0 Make all examples compile correctly
Nick Mathewson authored
196 //BUILD: FUNCTIONBODY INC:event2/event.h
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
197 .Example
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
198 [code,C]
199 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
200 int i;
6f89afc Make the examples build without warnings
Nick Mathewson authored
201 const char **methods = event_get_supported_methods();
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
202 printf("Starting Libevent %s. Available methods are:\n",
203 event_get_version());
204 for (i=0; methods[i] != NULL; ++i) {
205 printf(" %s\n", methods[i]);
206 }
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
207 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
208
209 NOTE: This function returns a list of the methods that Libevent was compiled
210 to support. It is possible that your operating system will not in fact
85b35f1 Initial editing pass from Susan.
@ authored
211 support them all when Libevent tries to run. For example, you could be on a
212 version of OSX where kqueue is too buggy to use.
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
213
214 .Interface
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
215 [code,C]
216 --------
0b1e73a Note a few functions that just got const-ized
Nick Mathewson authored
217 const char *event_base_get_method(const struct event_base *base);
218 enum event_method_feature event_base_get_features(const struct event_base *base);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
219 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
220
221 The event_base_get_method() call returns the name of the actual method in use
222 by an event_base. The event_base_get_features() call returns a bitmask of
223 the features that it supports.
224
53babe0 Make all examples compile correctly
Nick Mathewson authored
225 //BUILD: FUNCTIONBODY INC:event2/event.h
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
226 .Example
53babe0 Make all examples compile correctly
Nick Mathewson authored
227 [code,C]
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
228 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
229 struct event_base *base;
53babe0 Make all examples compile correctly
Nick Mathewson authored
230 enum event_method_feature f;
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
231
232 base = event_base_new();
233 if (!base) {
234 puts("Couldn't get an event_base!");
235 } else {
236 printf("Using Libevent with backend method %s.",
237 event_base_get_method(base));
238 f = event_base_get_features(base);
239 if ((f & EV_FEATURE_ET))
240 printf(" Edge-triggered events are supported.");
241 if ((f & EV_FEATURE_ET))
242 printf(" O(1) event notification is supported.");
243 if ((f & EV_FEATURE_FDS))
244 printf(" All FD types are supported.");
245 puts("");
246 }
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
247 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
248
249 These functions are defined in <event2/event.h>. The event_base_get_method()
250 call was first available in Libevent 1.4.3. The others first appeared in
251 Libevent 2.0.1-alpha.
252
253 Deallocating an event_base
254 ~~~~~~~~~~~~~~~~~~~~~~~~~~
255
256 When you are finished with an event_base, you can deallocate it with
257 event_base_free().
258
259 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored
260 [code,C]
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
261 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
262 void event_base_free(struct event_base *base);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
263 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
264
265 Note that this function does not deallocate any of the events that are
266 currently associated with the event_base, or close any of their sockets, or
267 free any of their pointers.
268
269 The event_base_free() function is defined in <event2/event.h>. It was first
270 implemented in Libevent 1.2.
271
272
273 Setting priorities on an event_base
274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
275
276 Libevent supports setting multiple priorities on an event. By default,
277 though, an event_base supports only a single priority level. You can set the
278 number of priorities on an event_base by calling event_base_priority_init().
279
280 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored
281 [code,C]
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
282 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
283 int event_base_priority_init(struct event_base *base, int n_priorities);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
284 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
285
286 This function returns 0 on success and -1 on failure. The 'base' argument is
287 the event_base to modify, and n_priorities is the number of priorities to
288 support. It must be at least 1. The available priorities for new events
289 will be numbered from 0 (most important) to n_priorities-1 (least important).
290
6d74d83 Clarify that npriorities has a hard limit
Nick Mathewson authored
291 There is a constant, EVENT_MAX_PRIORITIES, that sets the upper bound on the
292 value of n_priorities. It is an error to call this function with a higher
293 value for n_priorities.
294
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
295 NOTE: You *must* call this function before any events become active. It is
296 best to call it immediately after creating the event_base.
297
298 .Example
299
300 --------
301 For an example, see the documentation for event_priority_set below.
302 --------
303
304 By default, all new events associated with this base will be initialized
305 with priority equal to n_priorities / 2.
306
307 The event_base_priority_init function is defined in <event2/event.h>. It has
308 been available since before Libevent 1.0.
309
310
311 Reinitializing an event_base after fork()
312 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
313
314 Not all event backends persist cleanly after a call to fork(). Thus, if your
315 program uses fork() or a related system call in order to start a new process,
316 and you want to continue using an event_base after you have forked, you may
317 need to reinitialize it.
318
319 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored
320 [code,C]
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
321 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
322 int event_reinit(struct event_base *base);
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
323 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
324
325 The function returns 0 on success, -1 on failure.
326
53babe0 Make all examples compile correctly
Nick Mathewson authored
327 //BUILD: FUNCTIONBODY INC:event2/event.h INC:../example_stubs/Ref2.h INC:unistd.h
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
328 .Example
53babe0 Make all examples compile correctly
Nick Mathewson authored
329 [code,C]
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
330 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
331 struct event_base *base = event_base_new();
332
333 /* ... add some events to the event_base ... */
334
335 if (fork()) {
336 /* In parent */
337 continue_running_parent(base); /*...*/
338 } else {
339 /* In child */
340 event_reinit(base);
341 continue_running_child(base); /*...*/
342 }
ebf2f53 Add proper incantations to get correct, highlighted source in everyth…
Nick Mathewson authored
343 --------
b71b5e5 Insert a license file and start writing the reference manual
Nick Mathewson authored
344
345 The event_reinit() function is defined in <event2/event.h>. It was first
346 available in Libevent 1.4.3-alpha.
6b4d13a Add notes on working with deprecated functions
Nick Mathewson authored
347
348
349 Obsolete event_base functions
350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351
352 Older versions of Libevent relied pretty heavily on the idea of a
353 "current" event_base. The "current" event_base was a global setting
354 shared across all threads. If you forgot to specify which event_base
355 you wanted, you got the current one. Since event_bases weren't
356 threadsafe, this could get pretty error-prone.
357
358 Instead of event_base_new(), there was:
359
360 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored
361 [code,C]
6b4d13a Add notes on working with deprecated functions
Nick Mathewson authored
362 --------
363 struct event_base *event_init(void);
364 --------
365
366 This function worked like event_base_new(), and set the current base
3f42620 @shahn typo cleanup
shahn authored
367 to the allocated base. There was no other way to change the
5452465 spell-check.
Nick Mathewson authored
368 current base.
6b4d13a Add notes on working with deprecated functions
Nick Mathewson authored
369
370
371 Some of the event_base functions in this section had variants that
372 operated on the current base. These functions behaved as the current
373 functions, except that they took no base argument.
374
375 [options="header",width="85%"]
376 |======================================================================
377 | Current function | Obsolete current-base version
378 | event_base_priority_init() | event_priority_init()
379 | event_base_get_method() | event_get_method()
380 |======================================================================
381
fa74aaa Revise sections up to Ref5 for 2.0.3-alpha.
Nick Mathewson authored
382 // FIXME Undocumented:
383 // event_base_make_notifiable()
384
Something went wrong with that request. Please try again.