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

Comparing libev/ev.pod (file contents):
Revision 1.422 by root, Thu Nov 15 01:39:45 2012 UTC vs.
Revision 1.426 by root, Sat Feb 23 23:06:40 2013 UTC

… …
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