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

Comparing libev/ev.pod (file contents):
Revision 1.421 by root, Thu Aug 2 11:55:28 2012 UTC vs.
Revision 1.426 by root, Sat Feb 23 23:06:40 2013 UTC

… …
569kernel is more efficient (which says nothing about its actual speed, of 569kernel is more efficient (which says nothing about its actual speed, of
570course). While stopping, setting and starting an I/O watcher does never 570course). While stopping, setting and starting an I/O watcher does never
571cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to 571cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
572two event changes per incident. Support for C<fork ()> is very bad (you 572two event changes per incident. Support for C<fork ()> is very bad (you
573might have to leak fd's on fork, but it's more sane than epoll) and it 573might have to leak fd's on fork, but it's more sane than epoll) and it
574drops fds silently in similarly hard-to-detect cases 574drops fds silently in similarly hard-to-detect cases.
575 575
576This backend usually performs well under most conditions. 576This backend usually performs well under most conditions.
577 577
578While nominally embeddable in other event loops, this doesn't work 578While nominally embeddable in other event loops, this doesn't work
579everywhere, so you might need to test for this. And since it is broken 579everywhere, so you might need to test for this. And since it is broken
… …
1393transition between them will be described in more detail - and while these 1393transition between them will be described in more detail - and while these
1394rules might look complicated, they usually do "the right thing". 1394rules might look complicated, they usually do "the right thing".
1395 1395
1396=over 4 1396=over 4
1397 1397
1398=item initialiased 1398=item initialised
1399 1399
1400Before a watcher can be registered with the event loop it has to be 1400Before a watcher can be registered with the event loop it has to be
1401initialised. This can be done with a call to C<ev_TYPE_init>, or calls to 1401initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1402C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function. 1402C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1403 1403
… …
2606 2606
2607=head2 C<ev_stat> - did the file attributes just change? 2607=head2 C<ev_stat> - did the file attributes just change?
2608 2608
2609This watches a file system path for attribute changes. That is, it calls 2609This watches a file system path for attribute changes. That is, it calls
2610C<stat> on that path in regular intervals (or when the OS says it changed) 2610C<stat> on that path in regular intervals (or when the OS says it changed)
2611and sees if it changed compared to the last time, invoking the callback if 2611and sees if it changed compared to the last time, invoking the callback
2612it did. 2612if it did. Starting the watcher C<stat>'s the file, so only changes that
2613happen after the watcher has been started will be reported.
2613 2614
2614The path does not need to exist: changing from "path exists" to "path does 2615The path does not need to exist: changing from "path exists" to "path does
2615not exist" is a status change like any other. The condition "path does not 2616not exist" is a status change like any other. The condition "path does not
2616exist" (or more correctly "path cannot be stat'ed") is signified by the 2617exist" (or more correctly "path cannot be stat'ed") is signified by the
2617C<st_nlink> field being zero (which is otherwise always forced to be at 2618C<st_nlink> field being zero (which is otherwise always forced to be at
… …
3177 3178
3178=over 4 3179=over 4
3179 3180
3180=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 3181=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
3181 3182
3182=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 3183=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
3183 3184
3184Configures the watcher to embed the given loop, which must be 3185Configures the watcher to embed the given loop, which must be
3185embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 3186embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
3186invoked automatically, otherwise it is the responsibility of the callback 3187invoked automatically, otherwise it is the responsibility of the callback
3187to invoke it (it will continue to be called until the sweep has been done, 3188to invoke it (it will continue to be called until the sweep has been done,
… …
3658already been invoked. 3659already been invoked.
3659 3660
3660A common way around all these issues is to make sure that 3661A common way around all these issues is to make sure that
3661C<start_new_request> I<always> returns before the callback is invoked. If 3662C<start_new_request> I<always> returns before the callback is invoked. If
3662C<start_new_request> immediately knows the result, it can artificially 3663C<start_new_request> immediately knows the result, it can artificially
3663delay invoking the callback by e.g. using a C<prepare> or C<idle> watcher 3664delay invoking the callback by using a C<prepare> or C<idle> watcher for
3664for example, or more sneakily, by reusing an existing (stopped) watcher 3665example, or more sneakily, by reusing an existing (stopped) watcher and
3665and pushing it into the pending queue: 3666pushing it into the pending queue:
3666 3667
3667 ev_set_cb (watcher, callback); 3668 ev_set_cb (watcher, callback);
3668 ev_feed_event (EV_A_ watcher, 0); 3669 ev_feed_event (EV_A_ watcher, 0);
3669 3670
3670This way, C<start_new_request> can safely return before the callback is 3671This way, C<start_new_request> can safely return before the callback is
… …
3678 3679
3679This brings the problem of exiting - a callback might want to finish the 3680This brings the problem of exiting - a callback might want to finish the
3680main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but 3681main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
3681a modal "Are you sure?" dialog is still waiting), or just the nested one 3682a modal "Are you sure?" dialog is still waiting), or just the nested one
3682and not the main one (e.g. user clocked "Ok" in a modal dialog), or some 3683and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
3683other combination: In these cases, C<ev_break> will not work alone. 3684other combination: In these cases, a simple C<ev_break> will not work.
3684 3685
3685The solution is to maintain "break this loop" variable for each C<ev_run> 3686The solution is to maintain "break this loop" variable for each C<ev_run>
3686invocation, and use a loop around C<ev_run> until the condition is 3687invocation, and use a loop around C<ev_run> until the condition is
3687triggered, using C<EVRUN_ONCE>: 3688triggered, using C<EVRUN_ONCE>:
3688 3689
… …
4617different cpus (or different cpu cores). This reduces dependencies 4618different cpus (or different cpu cores). This reduces dependencies
4618and makes libev faster. 4619and makes libev faster.
4619 4620
4620=item EV_NO_THREADS 4621=item EV_NO_THREADS
4621 4622
4622If defined to be C<1>, libev will assume that it will never be called 4623If defined to be C<1>, libev will assume that it will never be called from
4623from different threads, which is a stronger assumption than C<EV_NO_SMP>, 4624different threads (that includes signal handlers), which is a stronger
4624above. This reduces dependencies and makes libev faster. 4625assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
4626libev faster.
4625 4627
4626=item EV_ATOMIC_T 4628=item EV_ATOMIC_T
4627 4629
4628Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4630Libev requires an integer type (suitable for storing C<0> or C<1>) whose
4629access is atomic with respect to other threads or signal contexts. No 4631access is atomic with respect to other threads or signal contexts. No

Diff Legend

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