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

Comparing libev/ev.pod (file contents):
Revision 1.423 by root, Fri Nov 23 12:52:35 2012 UTC vs.
Revision 1.431 by root, Fri Nov 22 16:42:10 2013 UTC

1=encoding utf-8
2
1=head1 NAME 3=head1 NAME
2 4
3libev - a high performance full-featured event loop written in C 5libev - a high performance full-featured event loop written in C
4 6
5=head1 SYNOPSIS 7=head1 SYNOPSIS
… …
396 398
397If this flag bit is or'ed into the flag value (or the program runs setuid 399If 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 400or setgid) then libev will I<not> look at the environment variable
399C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 401C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
400override the flags completely if it is found in the environment. This is 402override 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 403useful to try out specific backends to test their performance, to work
402around bugs. 404around bugs, or to make libev threadsafe (accessing environment variables
405cannot be done in a threadsafe way, but usually it works if no other
406thread modifies them).
403 407
404=item C<EVFLAG_FORKCHECK> 408=item C<EVFLAG_FORKCHECK>
405 409
406Instead of calling C<ev_loop_fork> manually after a fork, you can also 410Instead 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. 411make libev check for a fork in each iteration by enabling this flag.
… …
684reinitialise the kernel state for backends that have one. Despite the 688reinitialise the kernel state for backends that have one. Despite the
685name, you can call it anytime, but it makes most sense after forking, in 689name, you can call it anytime, but it makes most sense after forking, in
686the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the 690the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the
687child before resuming or calling C<ev_run>. 691child before resuming or calling C<ev_run>.
688 692
689Again, you I<have> to call it on I<any> loop that you want to re-use after 693Again, you I<have> to call it on I<any> loop that you want to re-use after
690a fork, I<even if you do not plan to use the loop in the parent>. This is 694a fork, I<even if you do not plan to use the loop in the parent>. This is
691because some kernel interfaces *cough* I<kqueue> *cough* do funny things 695because some kernel interfaces *cough* I<kqueue> *cough* do funny things
692during fork. 696during fork.
693 697
694On the other hand, you only need to call this function in the child 698On the other hand, you only need to call this function in the child
… …
2409only within the same loop, i.e. you can watch for C<SIGINT> in your 2413only within the same loop, i.e. you can watch for C<SIGINT> in your
2410default loop and for C<SIGIO> in another loop, but you cannot watch for 2414default loop and for C<SIGIO> in another loop, but you cannot watch for
2411C<SIGINT> in both the default loop and another loop at the same time. At 2415C<SIGINT> in both the default loop and another loop at the same time. At
2412the moment, C<SIGCHLD> is permanently tied to the default loop. 2416the moment, C<SIGCHLD> is permanently tied to the default loop.
2413 2417
2414When the first watcher gets started will libev actually register something 2418Only after the first watcher for a signal is started will libev actually
2415with the kernel (thus it coexists with your own signal handlers as long as 2419register something with the kernel. It thus coexists with your own signal
2416you don't register any with libev for the same signal). 2420handlers as long as you don't register any with libev for the same signal.
2417 2421
2418If possible and supported, libev will install its handlers with 2422If possible and supported, libev will install its handlers with
2419C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2423C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2420not be unduly interrupted. If you have a problem with system calls getting 2424not be unduly interrupted. If you have a problem with system calls getting
2421interrupted by signals you can block all signals in an C<ev_check> watcher 2425interrupted by signals you can block all signals in an C<ev_check> watcher
… …
2606 2610
2607=head2 C<ev_stat> - did the file attributes just change? 2611=head2 C<ev_stat> - did the file attributes just change?
2608 2612
2609This watches a file system path for attribute changes. That is, it calls 2613This 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) 2614C<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 2615and sees if it changed compared to the last time, invoking the callback
2612it did. 2616if it did. Starting the watcher C<stat>'s the file, so only changes that
2617happen after the watcher has been started will be reported.
2613 2618
2614The path does not need to exist: changing from "path exists" to "path does 2619The 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 2620not 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 2621exist" (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 2622C<st_nlink> field being zero (which is otherwise always forced to be at
… …
3177 3182
3178=over 4 3183=over 4
3179 3184
3180=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 3185=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
3181 3186
3182=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 3187=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
3183 3188
3184Configures the watcher to embed the given loop, which must be 3189Configures the watcher to embed the given loop, which must be
3185embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 3190embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
3186invoked automatically, otherwise it is the responsibility of the callback 3191invoked automatically, otherwise it is the responsibility of the callback
3187to invoke it (it will continue to be called until the sweep has been done, 3192to invoke it (it will continue to be called until the sweep has been done,
… …
3979Libev comes with some simplistic wrapper classes for C++ that mainly allow 3984Libev comes with some simplistic wrapper classes for C++ that mainly allow
3980you to use some convenience methods to start/stop watchers and also change 3985you to use some convenience methods to start/stop watchers and also change
3981the callback model to a model using method callbacks on objects. 3986the callback model to a model using method callbacks on objects.
3982 3987
3983To use it, 3988To use it,
3984 3989
3985 #include <ev++.h> 3990 #include <ev++.h>
3986 3991
3987This automatically includes F<ev.h> and puts all of its definitions (many 3992This automatically includes F<ev.h> and puts all of its definitions (many
3988of them macros) into the global namespace. All C++ specific things are 3993of them macros) into the global namespace. All C++ specific things are
3989put into the C<ev> namespace. It should support all the same embedding 3994put into the C<ev> namespace. It should support all the same embedding
… …
4617different cpus (or different cpu cores). This reduces dependencies 4622different cpus (or different cpu cores). This reduces dependencies
4618and makes libev faster. 4623and makes libev faster.
4619 4624
4620=item EV_NO_THREADS 4625=item EV_NO_THREADS
4621 4626
4622If defined to be C<1>, libev will assume that it will never be called 4627If 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>, 4628different threads (that includes signal handlers), which is a stronger
4624above. This reduces dependencies and makes libev faster. 4629assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
4630libev faster.
4625 4631
4626=item EV_ATOMIC_T 4632=item EV_ATOMIC_T
4627 4633
4628Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4634Libev 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 4635access is atomic with respect to other threads or signal contexts. No
… …
5425=over 4 5431=over 4
5426 5432
5427=item C<EV_COMPAT3> backwards compatibility mechanism 5433=item C<EV_COMPAT3> backwards compatibility mechanism
5428 5434
5429The backward compatibility mechanism can be controlled by 5435The backward compatibility mechanism can be controlled by
5430C<EV_COMPAT3>. See L</PREPROCESSOR SYMBOLS/MACROS> in the L</EMBEDDING> 5436C<EV_COMPAT3>. See L</"PREPROCESSOR SYMBOLS/MACROS"> in the L</EMBEDDING>
5431section. 5437section.
5432 5438
5433=item C<ev_default_destroy> and C<ev_default_fork> have been removed 5439=item C<ev_default_destroy> and C<ev_default_fork> have been removed
5434 5440
5435These calls can be replaced easily by their C<ev_loop_xxx> counterparts: 5441These calls can be replaced easily by their C<ev_loop_xxx> counterparts:

Diff Legend

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