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.428 by root, Thu May 30 18:51:57 2013 UTC

… …
396 396
397If this flag bit is or'ed into the flag value (or the program runs setuid 397If this flag bit is or'ed into the flag value (or the program runs setuid
398or setgid) then libev will I<not> look at the environment variable 398or setgid) then libev will I<not> look at the environment variable
399C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 399C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
400override the flags completely if it is found in the environment. This is 400override the flags completely if it is found in the environment. This is
401useful to try out specific backends to test their performance, or to work 401useful to try out specific backends to test their performance, to work
402around bugs. 402around bugs, or to make libev threadsafe (accessing environment variables
403cannot be done in a threadsafe way, but usually it works if no other
404thread modifies them).
403 405
404=item C<EVFLAG_FORKCHECK> 406=item C<EVFLAG_FORKCHECK>
405 407
406Instead of calling C<ev_loop_fork> manually after a fork, you can also 408Instead of calling C<ev_loop_fork> manually after a fork, you can also
407make libev check for a fork in each iteration by enabling this flag. 409make libev check for a fork in each iteration by enabling this flag.
… …
569kernel is more efficient (which says nothing about its actual speed, of 571kernel is more efficient (which says nothing about its actual speed, of
570course). While stopping, setting and starting an I/O watcher does never 572course). 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 573cause 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 574two 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 575might 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 576drops fds silently in similarly hard-to-detect cases.
575 577
576This backend usually performs well under most conditions. 578This backend usually performs well under most conditions.
577 579
578While nominally embeddable in other event loops, this doesn't work 580While nominally embeddable in other event loops, this doesn't work
579everywhere, so you might need to test for this. And since it is broken 581everywhere, 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 1395transition between them will be described in more detail - and while these
1394rules might look complicated, they usually do "the right thing". 1396rules might look complicated, they usually do "the right thing".
1395 1397
1396=over 4 1398=over 4
1397 1399
1398=item initialiased 1400=item initialised
1399 1401
1400Before a watcher can be registered with the event loop it has to be 1402Before 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 1403initialised. 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. 1404C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1403 1405
… …
2606 2608
2607=head2 C<ev_stat> - did the file attributes just change? 2609=head2 C<ev_stat> - did the file attributes just change?
2608 2610
2609This watches a file system path for attribute changes. That is, it calls 2611This 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) 2612C<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 2613and sees if it changed compared to the last time, invoking the callback
2612it did. 2614if it did. Starting the watcher C<stat>'s the file, so only changes that
2615happen after the watcher has been started will be reported.
2613 2616
2614The path does not need to exist: changing from "path exists" to "path does 2617The 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 2618not 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 2619exist" (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 2620C<st_nlink> field being zero (which is otherwise always forced to be at
… …
3177 3180
3178=over 4 3181=over 4
3179 3182
3180=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 3183=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
3181 3184
3182=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 3185=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
3183 3186
3184Configures the watcher to embed the given loop, which must be 3187Configures the watcher to embed the given loop, which must be
3185embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 3188embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
3186invoked automatically, otherwise it is the responsibility of the callback 3189invoked automatically, otherwise it is the responsibility of the callback
3187to invoke it (it will continue to be called until the sweep has been done, 3190to invoke it (it will continue to be called until the sweep has been done,
… …
3658already been invoked. 3661already been invoked.
3659 3662
3660A common way around all these issues is to make sure that 3663A common way around all these issues is to make sure that
3661C<start_new_request> I<always> returns before the callback is invoked. If 3664C<start_new_request> I<always> returns before the callback is invoked. If
3662C<start_new_request> immediately knows the result, it can artificially 3665C<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 3666delay invoking the callback by using a C<prepare> or C<idle> watcher for
3664for example, or more sneakily, by reusing an existing (stopped) watcher 3667example, or more sneakily, by reusing an existing (stopped) watcher and
3665and pushing it into the pending queue: 3668pushing it into the pending queue:
3666 3669
3667 ev_set_cb (watcher, callback); 3670 ev_set_cb (watcher, callback);
3668 ev_feed_event (EV_A_ watcher, 0); 3671 ev_feed_event (EV_A_ watcher, 0);
3669 3672
3670This way, C<start_new_request> can safely return before the callback is 3673This way, C<start_new_request> can safely return before the callback is
… …
3678 3681
3679This brings the problem of exiting - a callback might want to finish the 3682This 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 3683main 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 3684a 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 3685and 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. 3686other combination: In these cases, a simple C<ev_break> will not work.
3684 3687
3685The solution is to maintain "break this loop" variable for each C<ev_run> 3688The 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 3689invocation, and use a loop around C<ev_run> until the condition is
3687triggered, using C<EVRUN_ONCE>: 3690triggered, using C<EVRUN_ONCE>:
3688 3691
… …
3979Libev comes with some simplistic wrapper classes for C++ that mainly allow 3982Libev comes with some simplistic wrapper classes for C++ that mainly allow
3980you to use some convenience methods to start/stop watchers and also change 3983you to use some convenience methods to start/stop watchers and also change
3981the callback model to a model using method callbacks on objects. 3984the callback model to a model using method callbacks on objects.
3982 3985
3983To use it, 3986To use it,
3984 3987
3985 #include <ev++.h> 3988 #include <ev++.h>
3986 3989
3987This automatically includes F<ev.h> and puts all of its definitions (many 3990This automatically includes F<ev.h> and puts all of its definitions (many
3988of them macros) into the global namespace. All C++ specific things are 3991of them macros) into the global namespace. All C++ specific things are
3989put into the C<ev> namespace. It should support all the same embedding 3992put into the C<ev> namespace. It should support all the same embedding
… …
4617different cpus (or different cpu cores). This reduces dependencies 4620different cpus (or different cpu cores). This reduces dependencies
4618and makes libev faster. 4621and makes libev faster.
4619 4622
4620=item EV_NO_THREADS 4623=item EV_NO_THREADS
4621 4624
4622If defined to be C<1>, libev will assume that it will never be called 4625If 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>, 4626different threads (that includes signal handlers), which is a stronger
4624above. This reduces dependencies and makes libev faster. 4627assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
4628libev faster.
4625 4629
4626=item EV_ATOMIC_T 4630=item EV_ATOMIC_T
4627 4631
4628Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4632Libev 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 4633access is atomic with respect to other threads or signal contexts. No
… …
5425=over 4 5429=over 4
5426 5430
5427=item C<EV_COMPAT3> backwards compatibility mechanism 5431=item C<EV_COMPAT3> backwards compatibility mechanism
5428 5432
5429The backward compatibility mechanism can be controlled by 5433The backward compatibility mechanism can be controlled by
5430C<EV_COMPAT3>. See L</PREPROCESSOR SYMBOLS/MACROS> in the L</EMBEDDING> 5434C<EV_COMPAT3>. See L</"PREPROCESSOR SYMBOLS/MACROS"> in the L</EMBEDDING>
5431section. 5435section.
5432 5436
5433=item C<ev_default_destroy> and C<ev_default_fork> have been removed 5437=item C<ev_default_destroy> and C<ev_default_fork> have been removed
5434 5438
5435These calls can be replaced easily by their C<ev_loop_xxx> counterparts: 5439These calls can be replaced easily by their C<ev_loop_xxx> counterparts:

Diff Legend

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