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

Comparing libev/ev.pod (file contents):
Revision 1.412 by root, Fri May 4 20:47:50 2012 UTC vs.
Revision 1.413 by root, Fri May 4 20:50:02 2012 UTC

… …
82 82
83=head1 WHAT TO READ WHEN IN A HURRY 83=head1 WHAT TO READ WHEN IN A HURRY
84 84
85This manual tries to be very detailed, but unfortunately, this also makes 85This manual tries to be very detailed, but unfortunately, this also makes
86it very long. If you just want to know the basics of libev, I suggest 86it very long. If you just want to know the basics of libev, I suggest
87reading L<ANATOMY OF A WATCHER>, then the L<EXAMPLE PROGRAM> above and 87reading L</ANATOMY OF A WATCHER>, then the L<E/XAMPLE PROGRAM> above and
88look up the missing functions in L<GLOBAL FUNCTIONS> and the C<ev_io> and 88look up the missing functions in L</GLOBAL FUNCTIONS> and the C<ev_io> and
89C<ev_timer> sections in L<WATCHER TYPES>. 89C<ev_timer> sections in L</WATCHER TYPES>.
90 90
91=head1 ABOUT LIBEV 91=head1 ABOUT LIBEV
92 92
93Libev is an event loop: you register interest in certain events (such as a 93Libev is an event loop: you register interest in certain events (such as a
94file descriptor being readable or a timeout occurring), and it will manage 94file descriptor being readable or a timeout occurring), and it will manage
… …
764 764
765This function is rarely useful, but when some event callback runs for a 765This function is rarely useful, but when some event callback runs for a
766very long time without entering the event loop, updating libev's idea of 766very long time without entering the event loop, updating libev's idea of
767the current time is a good idea. 767the current time is a good idea.
768 768
769See also L<The special problem of time updates> in the C<ev_timer> section. 769See also L</The special problem of time updates> in the C<ev_timer> section.
770 770
771=item ev_suspend (loop) 771=item ev_suspend (loop)
772 772
773=item ev_resume (loop) 773=item ev_resume (loop)
774 774
… …
1346or might not have been clamped to the valid range. 1346or might not have been clamped to the valid range.
1347 1347
1348The default priority used by watchers when no priority has been set is 1348The default priority used by watchers when no priority has been set is
1349always C<0>, which is supposed to not be too high and not be too low :). 1349always C<0>, which is supposed to not be too high and not be too low :).
1350 1350
1351See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of 1351See L</WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1352priorities. 1352priorities.
1353 1353
1354=item ev_invoke (loop, ev_TYPE *watcher, int revents) 1354=item ev_invoke (loop, ev_TYPE *watcher, int revents)
1355 1355
1356Invoke the C<watcher> with the given C<loop> and C<revents>. Neither 1356Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
… …
1381See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related 1381See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1382functions that do not need a watcher. 1382functions that do not need a watcher.
1383 1383
1384=back 1384=back
1385 1385
1386See also the L<ASSOCIATING CUSTOM DATA WITH A WATCHER> and L<BUILDING YOUR 1386See also the L</ASSOCIATING CUSTOM DATA WITH A WATCHER> and L</BUILDING YOUR
1387OWN COMPOSITE WATCHERS> idioms. 1387OWN COMPOSITE WATCHERS> idioms.
1388 1388
1389=head2 WATCHER STATES 1389=head2 WATCHER STATES
1390 1390
1391There are various watcher states mentioned throughout this manual - 1391There are various watcher states mentioned throughout this manual -
… …
2136=item If the timer is repeating, make the C<repeat> value the new timeout 2136=item If the timer is repeating, make the C<repeat> value the new timeout
2137and start the timer, if necessary. 2137and start the timer, if necessary.
2138 2138
2139=back 2139=back
2140 2140
2141This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 2141This sounds a bit complicated, see L</Be smart about timeouts>, above, for a
2142usage example. 2142usage example.
2143 2143
2144=item ev_tstamp ev_timer_remaining (loop, ev_timer *) 2144=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
2145 2145
2146Returns the remaining time until a timer fires. If the timer is active, 2146Returns the remaining time until a timer fires. If the timer is active,
… …
2858 2858
2859This mode of operation can be useful together with an C<ev_check> watcher, 2859This mode of operation can be useful together with an C<ev_check> watcher,
2860to do something on each event loop iteration - for example to balance load 2860to do something on each event loop iteration - for example to balance load
2861between different connections. 2861between different connections.
2862 2862
2863See L<< Abusing an C<ev_check> watcher for its side-effect >> for a longer 2863See L<< /Abusing an C<ev_check> watcher for its side-effect >> for a longer
2864example. 2864example.
2865 2865
2866=head3 Watcher-Specific Functions and Data Members 2866=head3 Watcher-Specific Functions and Data Members
2867 2867
2868=over 4 2868=over 4
… …
3888You can do similar tricks if you have, say, threads with an event queue - 3888You can do similar tricks if you have, say, threads with an event queue -
3889instead of storing a coroutine, you store the queue object and instead of 3889instead of storing a coroutine, you store the queue object and instead of
3890switching to a coroutine, you push the watcher onto the queue and notify 3890switching to a coroutine, you push the watcher onto the queue and notify
3891any waiters. 3891any waiters.
3892 3892
3893To embed libev, see L<EMBEDDING>, but in short, it's easiest to create two 3893To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
3894files, F<my_ev.h> and F<my_ev.c> that include the respective libev files: 3894files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
3895 3895
3896 // my_ev.h 3896 // my_ev.h
3897 #define EV_CB_DECLARE(type) struct my_coro *cb; 3897 #define EV_CB_DECLARE(type) struct my_coro *cb;
3898 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb); 3898 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb);
… …
4993default loop and triggering an C<ev_async> watcher from the default loop 4993default loop and triggering an C<ev_async> watcher from the default loop
4994watcher callback into the event loop interested in the signal. 4994watcher callback into the event loop interested in the signal.
4995 4995
4996=back 4996=back
4997 4997
4998See also L<THREAD LOCKING EXAMPLE>. 4998See also L</THREAD LOCKING EXAMPLE>.
4999 4999
5000=head3 COROUTINES 5000=head3 COROUTINES
5001 5001
5002Libev is very accommodating to coroutines ("cooperative threads"): 5002Libev is very accommodating to coroutines ("cooperative threads"):
5003libev fully supports nesting calls to its functions from different 5003libev fully supports nesting calls to its functions from different
… …
5409=over 4 5409=over 4
5410 5410
5411=item C<EV_COMPAT3> backwards compatibility mechanism 5411=item C<EV_COMPAT3> backwards compatibility mechanism
5412 5412
5413The backward compatibility mechanism can be controlled by 5413The backward compatibility mechanism can be controlled by
5414C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING> 5414C<EV_COMPAT3>. See L</PREPROCESSOR SYMBOLS/MACROS> in the L</EMBEDDING>
5415section. 5415section.
5416 5416
5417=item C<ev_default_destroy> and C<ev_default_fork> have been removed 5417=item C<ev_default_destroy> and C<ev_default_fork> have been removed
5418 5418
5419These calls can be replaced easily by their C<ev_loop_xxx> counterparts: 5419These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
… …
5462=over 4 5462=over 4
5463 5463
5464=item active 5464=item active
5465 5465
5466A watcher is active as long as it has been started and not yet stopped. 5466A watcher is active as long as it has been started and not yet stopped.
5467See L<WATCHER STATES> for details. 5467See L</WATCHER STATES> for details.
5468 5468
5469=item application 5469=item application
5470 5470
5471In this document, an application is whatever is using libev. 5471In this document, an application is whatever is using libev.
5472 5472
… …
5508watchers and events. 5508watchers and events.
5509 5509
5510=item pending 5510=item pending
5511 5511
5512A watcher is pending as soon as the corresponding event has been 5512A watcher is pending as soon as the corresponding event has been
5513detected. See L<WATCHER STATES> for details. 5513detected. See L</WATCHER STATES> for details.
5514 5514
5515=item real time 5515=item real time
5516 5516
5517The physical time that is observed. It is apparently strictly monotonic :) 5517The physical time that is observed. It is apparently strictly monotonic :)
5518 5518

Diff Legend

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