Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 625 lines (624 sloc) 17.705 kb
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
1 .\" $OpenBSD: event.3,v 1.4 2002/07/12 18:50:48 provos Exp $
aa6567f @provos Initial revision
provos authored
2 .\"
3 .\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org>
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\"
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. The name of the author may not be used to endorse or promote products
16 .\" derived from this software without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
19 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
20 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21 .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
24 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
25 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
26 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
27 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 .\"
dcf6cbe @provos correct date
provos authored
29 .Dd August 8, 2000
aa6567f @provos Initial revision
provos authored
30 .Dt EVENT 3
31 .Os
32 .Sh NAME
33 .Nm event_init ,
34 .Nm event_dispatch ,
35 .Nm event_loop ,
cd699ab @provos support event_loopexit(); idea from marius; and fix event_once()
provos authored
36 .Nm event_loopexit ,
1c23e21 r14931@tombo: nickm | 2007-11-17 17:21:09 -0500
Nick Mathewson authored
37 .Nm event_loopbreak ,
3c74f06 @provos improved manpage from Phil Oleson
provos authored
38 .Nm event_set ,
39 .Nm event_base_dispatch ,
720f7fc @provos event_base_loop and some event logging fixes.
provos authored
40 .Nm event_base_loop ,
41 .Nm event_base_loopexit ,
1c23e21 r14931@tombo: nickm | 2007-11-17 17:21:09 -0500
Nick Mathewson authored
42 .Nm event_base_loopbreak ,
3c74f06 @provos improved manpage from Phil Oleson
provos authored
43 .Nm event_base_set ,
f5aa65c @provos man page fixes from todd miller
provos authored
44 .Nm event_base_free ,
aa6567f @provos Initial revision
provos authored
45 .Nm event_add ,
46 .Nm event_del ,
ec2c1db @provos new event_once interface; start of buffering interface for buffered even...
provos authored
47 .Nm event_once ,
41b7cbc @provos more the signal base into the event base; this removes global state and ...
provos authored
48 .Nm event_base_once ,
aa6567f @provos Initial revision
provos authored
49 .Nm event_pending ,
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
50 .Nm event_initialized ,
fa6c304 @provos support for event priorities; active events are scheduled into priority ...
provos authored
51 .Nm event_priority_init ,
52 .Nm event_priority_set ,
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
53 .Nm evtimer_set ,
54 .Nm evtimer_add ,
11a40d4 @provos event.3
provos authored
55 .Nm evtimer_del ,
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
56 .Nm evtimer_pending ,
57 .Nm evtimer_initialized ,
06630e3 @provos describe signal_*
provos authored
58 .Nm signal_set ,
59 .Nm signal_add ,
11a40d4 @provos event.3
provos authored
60 .Nm signal_del ,
06630e3 @provos describe signal_*
provos authored
61 .Nm signal_pending ,
3772ec8 @provos add new functions
provos authored
62 .Nm signal_initialized ,
63 .Nm bufferevent_new ,
64 .Nm bufferevent_free ,
65 .Nm bufferevent_write ,
66 .Nm bufferevent_write_buffer ,
67 .Nm bufferevent_read ,
68 .Nm bufferevent_enable ,
69 .Nm bufferevent_disable ,
70 .Nm bufferevent_settimeout ,
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
71 .Nm bufferevent_base_set ,
3772ec8 @provos add new functions
provos authored
72 .Nm evbuffer_new ,
73 .Nm evbuffer_free ,
74 .Nm evbuffer_add ,
75 .Nm evbuffer_add_buffer ,
76 .Nm evbuffer_add_printf ,
3c74f06 @provos improved manpage from Phil Oleson
provos authored
77 .Nm evbuffer_add_vprintf ,
3772ec8 @provos add new functions
provos authored
78 .Nm evbuffer_drain ,
79 .Nm evbuffer_write ,
80 .Nm evbuffer_read ,
1585013 @provos prototype addition; from Alexander von Gernler
provos authored
81 .Nm evbuffer_find ,
38b3304 @provos make a simple test for HTTP POST requests
provos authored
82 .Nm evbuffer_readline ,
67947ce @provos provide evhttp_new and evhttp_bind_socket instead of evhttp_start;
provos authored
83 .Nm evhttp_new ,
84 .Nm evhttp_bind_socket ,
38b3304 @provos make a simple test for HTTP POST requests
provos authored
85 .Nm evhttp_free
aa6567f @provos Initial revision
provos authored
86 .Nd execute a function when a specific event occurs
87 .Sh SYNOPSIS
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
88 .Fd #include <sys/time.h>
aa6567f @provos Initial revision
provos authored
89 .Fd #include <event.h>
cacd839 @provos documentation on thread safe events
provos authored
90 .Ft "struct event_base *"
f5aa65c @provos man page fixes from todd miller
provos authored
91 .Fn "event_init" "void"
aa6567f @provos Initial revision
provos authored
92 .Ft int
f5aa65c @provos man page fixes from todd miller
provos authored
93 .Fn "event_dispatch" "void"
aa6567f @provos Initial revision
provos authored
94 .Ft int
95 .Fn "event_loop" "int flags"
cd699ab @provos support event_loopexit(); idea from marius; and fix event_once()
provos authored
96 .Ft int
97 .Fn "event_loopexit" "struct timeval *tv"
1c23e21 r14931@tombo: nickm | 2007-11-17 17:21:09 -0500
Nick Mathewson authored
98 .Ft int
99 .Fn "event_loopbreak" "void"
aa6567f @provos Initial revision
provos authored
100 .Ft void
101 .Fn "event_set" "struct event *ev" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg"
102 .Ft int
3c74f06 @provos improved manpage from Phil Oleson
provos authored
103 .Fn "event_base_dispatch" "struct event_base *base"
104 .Ft int
105 .Fn "event_base_loop" "struct event_base *base" "int flags"
106 .Ft int
107 .Fn "event_base_loopexit" "struct event_base *base" "struct timeval *tv"
108 .Ft int
1c23e21 r14931@tombo: nickm | 2007-11-17 17:21:09 -0500
Nick Mathewson authored
109 .Fn "event_base_loopbreak" "struct event_base *base"
110 .Ft int
3c74f06 @provos improved manpage from Phil Oleson
provos authored
111 .Fn "event_base_set" "struct event_base *base" "struct event *"
f5aa65c @provos man page fixes from todd miller
provos authored
112 .Ft void
113 .Fn "event_base_free" "struct event_base *base"
3c74f06 @provos improved manpage from Phil Oleson
provos authored
114 .Ft int
aa6567f @provos Initial revision
provos authored
115 .Fn "event_add" "struct event *ev" "struct timeval *tv"
116 .Ft int
117 .Fn "event_del" "struct event *ev"
118 .Ft int
ec2c1db @provos new event_once interface; start of buffering interface for buffered even...
provos authored
119 .Fn "event_once" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
120 .Ft int
41b7cbc @provos more the signal base into the event base; this removes global state and ...
provos authored
121 .Fn "event_base_once" "struct event_base *base" "int fd" "short event" "void (*fn)(int, short, void *)" "void *arg" "struct timeval *tv"
122 .Ft int
aa6567f @provos Initial revision
provos authored
123 .Fn "event_pending" "struct event *ev" "short event" "struct timeval *tv"
124 .Ft int
125 .Fn "event_initialized" "struct event *ev"
fa6c304 @provos support for event priorities; active events are scheduled into priority ...
provos authored
126 .Ft int
127 .Fn "event_priority_init" "int npriorities"
128 .Ft int
129 .Fn "event_priority_set" "struct event *ev" "int priority"
aa6567f @provos Initial revision
provos authored
130 .Ft void
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
131 .Fn "evtimer_set" "struct event *ev" "void (*fn)(int, short, void *)" "void *arg"
aa6567f @provos Initial revision
provos authored
132 .Ft void
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
133 .Fn "evtimer_add" "struct event *ev" "struct timeval *"
aa6567f @provos Initial revision
provos authored
134 .Ft void
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
135 .Fn "evtimer_del" "struct event *ev"
aa6567f @provos Initial revision
provos authored
136 .Ft int
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
137 .Fn "evtimer_pending" "struct event *ev" "struct timeval *tv"
aa6567f @provos Initial revision
provos authored
138 .Ft int
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
139 .Fn "evtimer_initialized" "struct event *ev"
06630e3 @provos describe signal_*
provos authored
140 .Ft void
141 .Fn "signal_set" "struct event *ev" "int signal" "void (*fn)(int, short, void *)" "void *arg"
142 .Ft void
143 .Fn "signal_add" "struct event *ev" "struct timeval *"
144 .Ft void
145 .Fn "signal_del" "struct event *ev"
146 .Ft int
147 .Fn "signal_pending" "struct event *ev" "struct timeval *tv"
148 .Ft int
149 .Fn "signal_initialized" "struct event *ev"
3772ec8 @provos add new functions
provos authored
150 .Ft "struct bufferevent *"
151 .Fn "bufferevent_new" "int fd" "evbuffercb readcb" "evbuffercb writecb" "everrorcb" "void *cbarg"
152 .Ft void
153 .Fn "bufferevent_free" "struct bufferevent *bufev"
154 .Ft int
155 .Fn "bufferevent_write" "struct bufferevent *bufev" "void *data" "size_t size"
156 .Ft int
157 .Fn "bufferevent_write_buffer" "struct bufferevent *bufev" "struct evbuffer *buf"
158 .Ft size_t
159 .Fn "bufferevent_read" "struct bufferevent *bufev" "void *data" "size_t size"
160 .Ft int
161 .Fn "bufferevent_enable" "struct bufferevent *bufev" "short event"
162 .Ft int
163 .Fn "bufferevent_disable" "struct bufferevent *bufev" "short event"
164 .Ft void
165 .Fn "bufferevent_settimeout" "struct bufferevent *bufev" "int timeout_read" "int timeout_write"
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
166 .Ft int
167 .Fn "bufferevent_base_set" "struct event_base *base" "struct bufferevent *bufev"
3772ec8 @provos add new functions
provos authored
168 .Ft "struct evbuffer *"
169 .Fn "evbuffer_new" "void"
170 .Ft void
171 .Fn "evbuffer_free" "struct evbuffer *buf"
172 .Ft int
f5aa65c @provos man page fixes from todd miller
provos authored
173 .Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size"
3772ec8 @provos add new functions
provos authored
174 .Ft int
175 .Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src"
176 .Ft int
f5aa65c @provos man page fixes from todd miller
provos authored
177 .Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..."
3c74f06 @provos improved manpage from Phil Oleson
provos authored
178 .Ft int
179 .Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap"
3772ec8 @provos add new functions
provos authored
180 .Ft void
181 .Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size"
182 .Ft int
183 .Fn "evbuffer_write" "struct evbuffer *buf" "int fd"
184 .Ft int
185 .Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size"
186 .Ft "u_char *"
f5aa65c @provos man page fixes from todd miller
provos authored
187 .Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"
1585013 @provos prototype addition; from Alexander von Gernler
provos authored
188 .Ft "char *"
189 .Fn "evbuffer_readline" "struct evbuffer *buf"
38b3304 @provos make a simple test for HTTP POST requests
provos authored
190 .Ft "struct evhttp *"
8817310 @provos split libevent into two extra libraries libevent_core and libevent_extra
provos authored
191 .Fn "evhttp_new" "struct event_base *base"
67947ce @provos provide evhttp_new and evhttp_bind_socket instead of evhttp_start;
provos authored
192 .Ft int
193 .Fn "evhttp_bind_socket" "struct evhttp *http" "const char *address" "u_short port"
38b3304 @provos make a simple test for HTTP POST requests
provos authored
194 .Ft "void"
67947ce @provos provide evhttp_new and evhttp_bind_socket instead of evhttp_start;
provos authored
195 .Fn "evhttp_free" "struct evhttp *http"
aa6567f @provos Initial revision
provos authored
196 .Ft int
197 .Fa (*event_sigcb)(void) ;
f5aa65c @provos man page fixes from todd miller
provos authored
198 .Ft volatile sig_atomic_t
aa6567f @provos Initial revision
provos authored
199 .Fa event_gotsig ;
200 .Sh DESCRIPTION
201 The
202 .Nm event
203 API provides a mechanism to execute a function when a specific event
ac44ddd @provos grammar from jsyn@nthought.com
provos authored
204 on a file descriptor occurs or after a given time has passed.
aa6567f @provos Initial revision
provos authored
205 .Pp
206 The
207 .Nm event
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
208 API needs to be initialized with
aa6567f @provos Initial revision
provos authored
209 .Fn event_init
210 before it can be used.
211 .Pp
212 In order to process events, an application needs to call
213 .Fn event_dispatch .
ac44ddd @provos grammar from jsyn@nthought.com
provos authored
214 This function only returns on error, and should replace the event core
aa6567f @provos Initial revision
provos authored
215 of the application program.
216 .Pp
217 The function
218 .Fn event_set
219 prepares the event structure
220 .Fa ev
221 to be used in future calls to
222 .Fn event_add
223 and
224 .Fn event_del .
225 The event will be prepared to call the function specified by the
226 .Fa fn
227 argument with an
228 .Fa int
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
229 argument indicating the file descriptor, a
aa6567f @provos Initial revision
provos authored
230 .Fa short
231 argument indicating the type of event, and a
232 .Fa void *
233 argument given in the
234 .Fa arg
235 argument.
11a40d4 @provos event.3
provos authored
236 The
aa6567f @provos Initial revision
provos authored
237 .Fa fd
238 indicates the file descriptor that should be monitored for events.
239 The events can be either
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
240 .Va EV_READ ,
241 .Va EV_WRITE ,
11a40d4 @provos event.3
provos authored
242 or both,
243 indicating that an application can read or write from the file descriptor
aa6567f @provos Initial revision
provos authored
244 respectively without blocking.
245 .Pp
246 The function
247 .Fa fn
248 will be called with the file descriptor that triggered the event and
249 the type of event which will be either
250 .Va EV_TIMEOUT ,
06630e3 @provos describe signal_*
provos authored
251 .Va EV_SIGNAL ,
aa6567f @provos Initial revision
provos authored
252 .Va EV_READ ,
253 or
254 .Va EV_WRITE .
ccdc599 r15922@catbus: nickm | 2007-10-18 13:48:46 -0400
Nick Mathewson authored
255 Additionally, an event which has registered interest in more than one of the
256 preceeding events, via bitwise-OR to
257 .Fn event_set ,
258 can provide its callback function with a bitwise-OR of more than one triggered
259 event.
06630e3 @provos describe signal_*
provos authored
260 The additional flag
261 .Va EV_PERSIST
262 makes an
263 .Fn event_add
264 persistent until
265 .Fn event_del
266 has been called.
aa6567f @provos Initial revision
provos authored
267 .Pp
268 Once initialized, the
269 .Fa ev
06630e3 @provos describe signal_*
provos authored
270 structure can be used repeatedly with
aa6567f @provos Initial revision
provos authored
271 .Fn event_add
272 and
273 .Fn event_del
5f86585 @provos sync with openbsd; API change: timeout_ is now evtimer_
provos authored
274 and does not need to be reinitialized unless the function called and/or
275 the argument to it are to be changed.
11a40d4 @provos event.3
provos authored
276 However, when an
3ba224d @provos fixes for threaded operations from Andrew Danforth
provos authored
277 .Fa ev
11a40d4 @provos event.3
provos authored
278 structure has been added to libevent using
3ba224d @provos fixes for threaded operations from Andrew Danforth
provos authored
279 .Fn event_add
11a40d4 @provos event.3
provos authored
280 the structure must persist until the event occurs (assuming
281 .Fa EV_PERSIST
282 is not set) or is removed
283 using
284 .Fn event_del .
3ba224d @provos fixes for threaded operations from Andrew Danforth
provos authored
285 You may not reuse the same
11a40d4 @provos event.3
provos authored
286 .Fa ev
287 structure for multiple monitored descriptors; each descriptor
3ba224d @provos fixes for threaded operations from Andrew Danforth
provos authored
288 needs its own
289 .Fa ev .
aa6567f @provos Initial revision
provos authored
290 .Pp
291 The function
292 .Fn event_add
293 schedules the execution of the
294 .Fa ev
11a40d4 @provos event.3
provos authored
295 event when the event specified in
aa6567f @provos Initial revision
provos authored
296 .Fn event_set
297 occurs or in at least the time specified in the
298 .Fa tv .
299 If
300 .Fa tv
11a40d4 @provos event.3
provos authored
301 is
302 .Dv NULL ,
303 no timeout occurs and the function will only be called
aa6567f @provos Initial revision
provos authored
304 if a matching event occurs on the file descriptor.
305 The event in the
306 .Fa ev
307 argument must be already initialized by
308 .Fn event_set
309 and may not be used in calls to
310 .Fn event_set
311 until it has timed out or been removed with
312 .Fn event_del .
313 If the event in the
314 .Fa ev
ac44ddd @provos grammar from jsyn@nthought.com
provos authored
315 argument already has a scheduled timeout, the old timeout will be
aa6567f @provos Initial revision
provos authored
316 replaced by the new one.
317 .Pp
318 The function
319 .Fn event_del
320 will cancel the event in the argument
321 .Fa ev .
322 If the event has already executed or has never been added
323 the call will have no effect.
324 .Pp
ccdc599 r15922@catbus: nickm | 2007-10-18 13:48:46 -0400
Nick Mathewson authored
325 The functions
326 .Fn evtimer_set ,
327 .Fn evtimer_add ,
328 .Fn evtimer_del ,
329 .Fn evtimer_initialized ,
330 and
331 .Fn evtimer_pending
332 are abbreviations for common situations where only a timeout is required.
333 The file descriptor passed will be \-1, and the event type will be
334 .Va EV_TIMEOUT .
335 .Pp
336 The functions
337 .Fn signal_set ,
338 .Fn signal_add ,
339 .Fn signal_del ,
340 .Fn signal_initialized ,
341 and
342 .Fn signal_pending
343 are abbreviations.
344 The event type will be a persistent
345 .Va EV_SIGNAL .
346 That means
347 .Fn signal_set
348 adds
349 .Va EV_PERSIST .
350 .Pp
351 In order to avoid races in signal handlers, the
352 .Nm event
353 API provides two variables:
354 .Va event_sigcb
355 and
356 .Va event_gotsig .
357 A signal handler
358 sets
359 .Va event_gotsig
360 to indicate that a signal has been received.
361 The application sets
362 .Va event_sigcb
363 to a callback function.
364 After the signal handler sets
365 .Va event_gotsig ,
366 .Nm event_dispatch
367 will execute the callback function to process received signals.
368 The callback returns 1 when no events are registered any more.
369 It can return \-1 to indicate an error to the
370 .Nm event
371 library, causing
372 .Fn event_dispatch
373 to terminate with
374 .Va errno
375 set to
376 .Er EINTR .
377 .Pp
ec2c1db @provos new event_once interface; start of buffering interface for buffered even...
provos authored
378 The function
379 .Fn event_once
bca504e @provos fix typos
provos authored
380 is similar to
ec2c1db @provos new event_once interface; start of buffering interface for buffered even...
provos authored
381 .Fn event_set .
382 However, it schedules a callback to be called exactly once and does not
383 require the caller to prepare an
384 .Fa event
385 structure.
386 This function supports
387 .Fa EV_TIMEOUT ,
11a40d4 @provos event.3
provos authored
388 .Fa EV_READ ,
ec2c1db @provos new event_once interface; start of buffering interface for buffered even...
provos authored
389 and
390 .Fa EV_WRITE .
391 .Pp
aa6567f @provos Initial revision
provos authored
392 The
393 .Fn event_pending
394 function can be used to check if the event specified by
395 .Fa event
396 is pending to run.
397 If
398 .Va EV_TIMEOUT
11a40d4 @provos event.3
provos authored
399 was specified and
aa6567f @provos Initial revision
provos authored
400 .Fa tv
401 is not
11a40d4 @provos event.3
provos authored
402 .Dv NULL ,
aa6567f @provos Initial revision
provos authored
403 the expiration time of the event will be returned in
404 .Fa tv .
405 .Pp
406 The
407 .Fn event_initialized
408 macro can be used to check if an event has been initialized.
409 .Pp
ccdc599 r15922@catbus: nickm | 2007-10-18 13:48:46 -0400
Nick Mathewson authored
410 The
411 .Nm event_loop
412 function provides an interface for single pass execution of pending
413 events.
414 The flags
415 .Va EVLOOP_ONCE
aa6567f @provos Initial revision
provos authored
416 and
ccdc599 r15922@catbus: nickm | 2007-10-18 13:48:46 -0400
Nick Mathewson authored
417 .Va EVLOOP_NONBLOCK
418 are recognized.
419 The
420 .Nm event_loopexit
70248ca r14930@tombo: nickm | 2007-11-17 17:01:14 -0500
Nick Mathewson authored
421 function exits from the event loop. The next
422 .Fn event_loop
423 iteration after the
424 given timer expires will complete normally (handling all queued events) then
425 exit without blocking for events again. Subsequent invocations of
426 .Fn event_loop
427 will proceed normally.
1c23e21 r14931@tombo: nickm | 2007-11-17 17:21:09 -0500
Nick Mathewson authored
428 The
429 .Nm event_loopbreak
430 function exits from the event loop immediately.
431 .Fn event_loop
432 will abort after the next event is completed;
433 .Fn event_loopbreak
434 is typically invoked from this event's callback. This behavior is analogous
435 to the "break;" statement. Subsequent invocations of
436 .Fn event_loop
437 will proceed normally.
aa6567f @provos Initial revision
provos authored
438 .Pp
ccdc599 r15922@catbus: nickm | 2007-10-18 13:48:46 -0400
Nick Mathewson authored
439 It is the responsibility of the caller to provide these functions with
440 pre-allocated event structures.
06630e3 @provos describe signal_*
provos authored
441 .Pp
fa6c304 @provos support for event priorities; active events are scheduled into priority ...
provos authored
442 .Sh EVENT PRIORITIES
443 By default
444 .Nm libevent
445 schedules all active events with the same priority.
11a40d4 @provos event.3
provos authored
446 However, sometimes it is desirable to process some events with a higher
fa6c304 @provos support for event priorities; active events are scheduled into priority ...
provos authored
447 priority than others.
448 For that reason,
449 .Nm libevent
450 supports strict priority queues.
451 Active events with a lower priority are always processed before events
452 with a higher priority.
453 .Pp
454 The number of different priorities can be set initially with the
455 .Fn event_priority_init
456 function.
457 This function should be called before the first call to
458 .Fn event_dispatch .
459 The
460 .Fn event_priority_set
461 function can be used to assign a priority to an event.
462 By default,
463 .Nm libevent
464 assigns the middle priority to all events unless their priority
465 is explicitly set.
cacd839 @provos documentation on thread safe events
provos authored
466 .Sh THREAD SAFE EVENTS
467 .Nm Libevent
468 has experimental support for thread-safe events.
469 When initializing the library via
470 .Fn event_init ,
471 an event base is returned.
472 This event base can be used in conjunction with calls to
11a40d4 @provos event.3
provos authored
473 .Fn event_base_set ,
720f7fc @provos event_base_loop and some event logging fixes.
provos authored
474 .Fn event_base_dispatch ,
475 .Fn event_base_loop ,
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
476 .Fn event_base_loopexit ,
f5aa65c @provos man page fixes from todd miller
provos authored
477 .Fn bufferevent_base_set
cacd839 @provos documentation on thread safe events
provos authored
478 and
f5aa65c @provos man page fixes from todd miller
provos authored
479 .Fn event_base_free .
11a40d4 @provos event.3
provos authored
480 .Fn event_base_set
3ba224d @provos fixes for threaded operations from Andrew Danforth
provos authored
481 should be called after preparing an event with
11a40d4 @provos event.3
provos authored
482 .Fn event_set ,
3ba224d @provos fixes for threaded operations from Andrew Danforth
provos authored
483 as
11a40d4 @provos event.3
provos authored
484 .Fn event_set
3ba224d @provos fixes for threaded operations from Andrew Danforth
provos authored
485 assigns the provided event to the most recently created event base.
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
486 .Fn bufferevent_base_set
487 should be called after preparing a bufferevent with
488 .Fn bufferevent_new .
f5aa65c @provos man page fixes from todd miller
provos authored
489 .Fn event_base_free
490 should be used to free memory associated with the event base
491 when it is no longer needed.
8f2e1f6 @provos add section about buffered events
provos authored
492 .Sh BUFFERED EVENTS
493 .Nm libevent
494 provides an abstraction on top of the regular event callbacks.
495 This abstraction is called a
496 .Va "buffered event" .
11a40d4 @provos event.3
provos authored
497 A buffered event provides input and output buffers that get filled
8f2e1f6 @provos add section about buffered events
provos authored
498 and drained automatically.
499 The user of a buffered event no longer deals directly with the IO,
24ffe1c @provos add a section about BUGS
provos authored
500 but instead is reading from input and writing to output buffers.
8f2e1f6 @provos add section about buffered events
provos authored
501 .Pp
502 A new bufferevent is created by
503 .Fn bufferevent_new .
504 The parameter
11a40d4 @provos event.3
provos authored
505 .Fa fd
8f2e1f6 @provos add section about buffered events
provos authored
506 specifies the file descriptor from which data is read and written to.
11a40d4 @provos event.3
provos authored
507 This file descriptor is not allowed to be a
8f2e1f6 @provos add section about buffered events
provos authored
508 .Xr pipe 2 .
509 The next three parameters are callbacks.
11a40d4 @provos event.3
provos authored
510 The read and write callback have the following form:
8f2e1f6 @provos add section about buffered events
provos authored
511 .Ft void
11a40d4 @provos event.3
provos authored
512 .Fn "(*cb)" "struct bufferevent *bufev" "void *arg" .
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
513 The error callback has the following form:
514 .Ft void
515 .Fn "(*cb)" "struct bufferevent *bufev" "short what" "void *arg" .
8f2e1f6 @provos add section about buffered events
provos authored
516 The argument is specified by the fourth parameter
517 .Fa "cbarg" .
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
518 A
519 .Fa bufferevent struct
520 pointer is returned on success, NULL on error.
b0b5e2c @provos document that read and write callbacks may be NULL.
provos authored
521 Both the read and the write callback may be NULL.
522 The error callback has to be always provided.
8f2e1f6 @provos add section about buffered events
provos authored
523 .Pp
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
524 Once initialized, the bufferevent structure can be used repeatedly with
f5aa65c @provos man page fixes from todd miller
provos authored
525 bufferevent_enable() and bufferevent_disable().
526 The flags parameter can be a combination of
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
527 .Va EV_READ
528 and
529 .Va EV_WRITE .
f5aa65c @provos man page fixes from todd miller
provos authored
530 When read enabled the bufferevent will try to read from the file
531 descriptor and call the read callback.
532 The write callback is executed
533 whenever the output buffer is drained below the write low watermark,
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
534 which is
8f2e1f6 @provos add section about buffered events
provos authored
535 .Va 0
536 by default.
537 .Pp
538 The
539 .Fn bufferevent_write
540 function can be used to write data to the file descriptor.
541 The data is appended to the output buffer and written to the descriptor
542 automatically as it becomes available for writing.
f5aa65c @provos man page fixes from todd miller
provos authored
543 .Fn bufferevent_write
544 returns 0 on success or \-1 on failure.
8f2e1f6 @provos add section about buffered events
provos authored
545 The
546 .Fn bufferevent_read
f5aa65c @provos man page fixes from todd miller
provos authored
547 function is used to read data from the input buffer,
548 returning the amount of data read.
f296e63 @provos allow setting an event base for bufferevents; from phil oleson
provos authored
549 .Pp
550 If multiple bases are in use, bufferevent_base_set() must be called before
551 enabling the bufferevent for the first time.
38b3304 @provos make a simple test for HTTP POST requests
provos authored
552 .Sh NON-BLOCKING HTTP SUPPORT
553 .Nm libevent
554 provides a very thin HTTP layer that can be used both to host an HTTP
555 server and also to make HTTP requests.
556 An HTTP server can be created by calling
67947ce @provos provide evhttp_new and evhttp_bind_socket instead of evhttp_start;
provos authored
557 .Fn evhttp_new .
558 It can be bound to any port and address with the
559 .Fn evhttp_bind_socket
560 function.
38b3304 @provos make a simple test for HTTP POST requests
provos authored
561 When the HTTP server is no longer used, it can be freed via
562 .Fn evhttp_free .
563 .Pp
564 To be notified of HTTP requests, a user needs to register callbacks with the
565 HTTP server.
566 This can be done by calling
567 .Fn evhttp_set_cb .
568 The second argument is the URI for which a callback is being registered.
569 The corresponding callback will receive an
570 .Va struct evhttp_request
f5aa65c @provos man page fixes from todd miller
provos authored
571 object that contains all information about the request.
38b3304 @provos make a simple test for HTTP POST requests
provos authored
572 .Pp
f5aa65c @provos man page fixes from todd miller
provos authored
573 This section does not document all the possible function calls; please
38b3304 @provos make a simple test for HTTP POST requests
provos authored
574 check
575 .Va event.h
576 for the public interfaces.
ccdc599 r15922@catbus: nickm | 2007-10-18 13:48:46 -0400
Nick Mathewson authored
577 .Sh ADDITIONAL NOTES
578 It is possible to disable support for
579 .Va epoll , kqueue , devpoll , poll
580 or
581 .Va select
582 by setting the environment variable
583 .Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL
584 or
585 .Va EVENT_NOSELECT ,
586 respectively.
587 By setting the environment variable
588 .Va EVENT_SHOW_METHOD ,
589 .Nm libevent
590 displays the kernel notification method that it uses.
aa6567f @provos Initial revision
provos authored
591 .Sh RETURN VALUES
592 Upon successful completion
593 .Fn event_add
594 and
595 .Fn event_del
596 return 0.
11a40d4 @provos event.3
provos authored
597 Otherwise, \-1 is returned and the global variable errno is
aa6567f @provos Initial revision
provos authored
598 set to indicate the error.
599 .Sh SEE ALSO
11a40d4 @provos event.3
provos authored
600 .Xr kqueue 2 ,
601 .Xr poll 2 ,
aa6567f @provos Initial revision
provos authored
602 .Xr select 2 ,
f5aa65c @provos man page fixes from todd miller
provos authored
603 .Xr evdns 3 ,
11a40d4 @provos event.3
provos authored
604 .Xr timeout 9
aa6567f @provos Initial revision
provos authored
605 .Sh HISTORY
606 The
607 .Nm event
608 API manpage is based on the
609 .Xr timeout 9
610 manpage by Artur Grabowski.
e0216ed @provos credits
provos authored
611 The port of
612 .Nm libevent
613 to Windows is due to Michael A. Davis.
614 Support for real-time signals is due to Taral.
aa6567f @provos Initial revision
provos authored
615 .Sh AUTHORS
616 The
617 .Nm event
618 library was written by Niels Provos.
24ffe1c @provos add a section about BUGS
provos authored
619 .Sh BUGS
bca504e @provos fix typos
provos authored
620 This documentation is neither complete nor authoritative.
24ffe1c @provos add a section about BUGS
provos authored
621 If you are in doubt about the usage of this API then
622 check the source code to find out how it works, write
623 up the missing piece of documentation and send it to
624 me for inclusion in this man page.
Something went wrong with that request. Please try again.