ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.178 by root, Sat Sep 13 18:25:50 2008 UTC vs.
Revision 1.181 by root, Fri Sep 19 03:47:50 2008 UTC

… …
359writing a server, you should C<accept ()> in a loop to accept as many 359writing a server, you should C<accept ()> in a loop to accept as many
360connections as possible during one iteration. You might also want to have 360connections as possible during one iteration. You might also want to have
361a look at C<ev_set_io_collect_interval ()> to increase the amount of 361a look at C<ev_set_io_collect_interval ()> to increase the amount of
362readiness notifications you get per iteration. 362readiness notifications you get per iteration.
363 363
364This backend maps C<EV_READ> to the C<readfds> set and C<EV_WRITE> to the
365C<writefds> set (and to work around Microsoft Windows bugs, also onto the
366C<exceptfds> set on that platform).
367
364=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows) 368=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
365 369
366And this is your standard poll(2) backend. It's more complicated 370And this is your standard poll(2) backend. It's more complicated
367than select, but handles sparse fds better and has no artificial 371than select, but handles sparse fds better and has no artificial
368limit on the number of fds you can use (except it will slow down 372limit on the number of fds you can use (except it will slow down
369considerably with a lot of inactive fds). It scales similarly to select, 373considerably with a lot of inactive fds). It scales similarly to select,
370i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for 374i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
371performance tips. 375performance tips.
376
377This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
378C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
372 379
373=item C<EVBACKEND_EPOLL> (value 4, Linux) 380=item C<EVBACKEND_EPOLL> (value 4, Linux)
374 381
375For few fds, this backend is a bit little slower than poll and select, 382For few fds, this backend is a bit little slower than poll and select,
376but it scales phenomenally better. While poll and select usually scale 383but it scales phenomenally better. While poll and select usually scale
… …
395keep at least one watcher active per fd at all times. 402keep at least one watcher active per fd at all times.
396 403
397While nominally embeddable in other event loops, this feature is broken in 404While nominally embeddable in other event loops, this feature is broken in
398all kernel versions tested so far. 405all kernel versions tested so far.
399 406
407This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
408C<EVBACKEND_POLL>.
409
400=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 410=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
401 411
402Kqueue deserves special mention, as at the time of this writing, it 412Kqueue deserves special mention, as at the time of this writing, it
403was broken on all BSDs except NetBSD (usually it doesn't work reliably 413was broken on all BSDs except NetBSD (usually it doesn't work reliably
404with anything but sockets and pipes, except on Darwin, where of course 414with anything but sockets and pipes, except on Darwin, where of course
… …
425almost everywhere, you should only use it when you have a lot of sockets 435almost everywhere, you should only use it when you have a lot of sockets
426(for which it usually works), by embedding it into another event loop 436(for which it usually works), by embedding it into another event loop
427(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for 437(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
428sockets. 438sockets.
429 439
440This backend maps C<EV_READ> into an C<EVFILT_READ> kevent with
441C<NOTE_EOF>, and C<EV_WRITE> into an C<EVFILT_WRITE> kevent with
442C<NOTE_EOF>.
443
430=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8) 444=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
431 445
432This is not implemented yet (and might never be, unless you send me an 446This is not implemented yet (and might never be, unless you send me an
433implementation). According to reports, C</dev/poll> only supports sockets 447implementation). According to reports, C</dev/poll> only supports sockets
434and is not embeddable, which would limit the usefulness of this backend 448and is not embeddable, which would limit the usefulness of this backend
… …
449might perform better. 463might perform better.
450 464
451On the positive side, ignoring the spurious readiness notifications, this 465On the positive side, ignoring the spurious readiness notifications, this
452backend actually performed to specification in all tests and is fully 466backend actually performed to specification in all tests and is fully
453embeddable, which is a rare feat among the OS-specific backends. 467embeddable, which is a rare feat among the OS-specific backends.
468
469This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
470C<EVBACKEND_POLL>.
454 471
455=item C<EVBACKEND_ALL> 472=item C<EVBACKEND_ALL>
456 473
457Try all backends (even potentially broken ones that wouldn't be tried 474Try all backends (even potentially broken ones that wouldn't be tried
458with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 475with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
… …
3223 3240
3224=head1 THREADS AND COROUTINES 3241=head1 THREADS AND COROUTINES
3225 3242
3226=head2 THREADS 3243=head2 THREADS
3227 3244
3228Libev itself is completely thread-safe, but it uses no locking. This 3245Libev itself is thread-safe (unless the opposite is specifically
3246documented for a function), but it uses no locking itself. This means that
3229means that you can use as many loops as you want in parallel, as long as 3247you can use as many loops as you want in parallel, as long as only one
3230only one thread ever calls into one libev function with the same loop 3248thread ever calls into one libev function with the same loop parameter:
3231parameter. 3249libev guarentees that different event loops share no data structures that
3250need locking.
3232 3251
3233Or put differently: calls with different loop parameters can be done in 3252Or to put it differently: calls with different loop parameters can be done
3234parallel from multiple threads, calls with the same loop parameter must be 3253concurrently from multiple threads, calls with the same loop parameter
3235done serially (but can be done from different threads, as long as only one 3254must be done serially (but can be done from different threads, as long as
3236thread ever is inside a call at any point in time, e.g. by using a mutex 3255only one thread ever is inside a call at any point in time, e.g. by using
3237per loop). 3256a mutex per loop).
3257
3258Specifically to support threads (and signal handlers), libev implements
3259so-called C<ev_async> watchers, which allow some limited form of
3260concurrency on the same event loop.
3238 3261
3239If you want to know which design (one loop, locking, or multiple loops 3262If you want to know which design (one loop, locking, or multiple loops
3240without or something else still) is best for your problem, then I cannot 3263without or something else still) is best for your problem, then I cannot
3241help you. I can give some generic advice however: 3264help you. I can give some generic advice however:
3242 3265
… …
3260better than you currently do :-) 3283better than you currently do :-)
3261 3284
3262=item * often you need to talk to some other thread which blocks in the 3285=item * often you need to talk to some other thread which blocks in the
3263event loop - C<ev_async> watchers can be used to wake them up from other 3286event loop - C<ev_async> watchers can be used to wake them up from other
3264threads safely (or from signal contexts...). 3287threads safely (or from signal contexts...).
3288
3289=item * some watcher types are only supported in the default loop - use
3290C<ev_async> watchers to tell your other loops about any such events.
3265 3291
3266=back 3292=back
3267 3293
3268=head2 COROUTINES 3294=head2 COROUTINES
3269 3295
… …
3272coroutines (e.g. you can call C<ev_loop> on the same loop from two 3298coroutines (e.g. you can call C<ev_loop> on the same loop from two
3273different coroutines and switch freely between both coroutines running the 3299different coroutines and switch freely between both coroutines running the
3274loop, as long as you don't confuse yourself). The only exception is that 3300loop, as long as you don't confuse yourself). The only exception is that
3275you must not do this from C<ev_periodic> reschedule callbacks. 3301you must not do this from C<ev_periodic> reschedule callbacks.
3276 3302
3277Care has been invested into making sure that libev does not keep local 3303Care has been taken to ensure that libev does not keep local state inside
3278state inside C<ev_loop>, and other calls do not usually allow coroutine 3304C<ev_loop>, and other calls do not usually allow coroutine switches.
3279switches.
3280 3305
3281 3306
3282=head1 COMPLEXITIES 3307=head1 COMPLEXITIES
3283 3308
3284In this section the complexities of (many of) the algorithms used inside 3309In this section the complexities of (many of) the algorithms used inside

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines