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

Comparing libev/ev.pod (file contents):
Revision 1.31 by root, Fri Nov 23 05:00:45 2007 UTC vs.
Revision 1.34 by root, Fri Nov 23 16:17:12 2007 UTC

… …
45 45
46Libev represents time as a single floating point number, representing the 46Libev represents time as a single floating point number, representing the
47(fractional) number of seconds since the (POSIX) epoch (somewhere near 47(fractional) number of seconds since the (POSIX) epoch (somewhere near
48the beginning of 1970, details are complicated, don't ask). This type is 48the beginning of 1970, details are complicated, don't ask). This type is
49called C<ev_tstamp>, which is what you should use too. It usually aliases 49called C<ev_tstamp>, which is what you should use too. It usually aliases
50to the double type in C. 50to the C<double> type in C, and when you need to do any calculations on
51it, you should treat it as such.
52
51 53
52=head1 GLOBAL FUNCTIONS 54=head1 GLOBAL FUNCTIONS
53 55
54These functions can be called anytime, even before initialising the 56These functions can be called anytime, even before initialising the
55library in any way. 57library in any way.
… …
75Usually, it's a good idea to terminate if the major versions mismatch, 77Usually, it's a good idea to terminate if the major versions mismatch,
76as this indicates an incompatible change. Minor versions are usually 78as this indicates an incompatible change. Minor versions are usually
77compatible to older versions, so a larger minor version alone is usually 79compatible to older versions, so a larger minor version alone is usually
78not a problem. 80not a problem.
79 81
82Example: make sure we haven't accidentally been linked against the wrong
83version:
84
85 assert (("libev version mismatch",
86 ev_version_major () == EV_VERSION_MAJOR
87 && ev_version_minor () >= EV_VERSION_MINOR));
88
80=item unsigned int ev_supported_backends () 89=item unsigned int ev_supported_backends ()
81 90
82Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*> 91Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
83value) compiled into this binary of libev (independent of their 92value) compiled into this binary of libev (independent of their
84availability on the system you are running on). See C<ev_default_loop> for 93availability on the system you are running on). See C<ev_default_loop> for
85a description of the set values. 94a description of the set values.
95
96Example: make sure we have the epoll method, because yeah this is cool and
97a must have and can we have a torrent of it please!!!11
98
99 assert (("sorry, no epoll, no sex",
100 ev_supported_backends () & EVBACKEND_EPOLL));
86 101
87=item unsigned int ev_recommended_backends () 102=item unsigned int ev_recommended_backends ()
88 103
89Return the set of all backends compiled into this binary of libev and also 104Return the set of all backends compiled into this binary of libev and also
90recommended for this platform. This set is often smaller than the one 105recommended for this platform. This set is often smaller than the one
91returned by C<ev_supported_backends>, as for example kqueue is broken on 106returned by C<ev_supported_backends>, as for example kqueue is broken on
92most BSDs and will not be autodetected unless you explicitly request it 107most BSDs and will not be autodetected unless you explicitly request it
93(assuming you know what you are doing). This is the set of backends that 108(assuming you know what you are doing). This is the set of backends that
94C<EVFLAG_AUTO> will probe for. 109libev will probe for if you specify no backends explicitly.
95 110
96=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 111=item ev_set_allocator (void *(*cb)(void *ptr, long size))
97 112
98Sets the allocation function to use (the prototype is similar to the 113Sets the allocation function to use (the prototype is similar to the
99realloc C function, the semantics are identical). It is used to allocate 114realloc C function, the semantics are identical). It is used to allocate
… …
102destructive action. The default is your system realloc function. 117destructive action. The default is your system realloc function.
103 118
104You could override this function in high-availability programs to, say, 119You could override this function in high-availability programs to, say,
105free some memory if it cannot allocate memory, to use a special allocator, 120free some memory if it cannot allocate memory, to use a special allocator,
106or even to sleep a while and retry until some memory is available. 121or even to sleep a while and retry until some memory is available.
122
123Example: replace the libev allocator with one that waits a bit and then
124retries: better than mine).
125
126 static void *
127 persistent_realloc (void *ptr, long size)
128 {
129 for (;;)
130 {
131 void *newptr = realloc (ptr, size);
132
133 if (newptr)
134 return newptr;
135
136 sleep (60);
137 }
138 }
139
140 ...
141 ev_set_allocator (persistent_realloc);
107 142
108=item ev_set_syserr_cb (void (*cb)(const char *msg)); 143=item ev_set_syserr_cb (void (*cb)(const char *msg));
109 144
110Set the callback function to call on a retryable syscall error (such 145Set the callback function to call on a retryable syscall error (such
111as failed select, poll, epoll_wait). The message is a printable string 146as failed select, poll, epoll_wait). The message is a printable string
… …
113callback is set, then libev will expect it to remedy the sitution, no 148callback is set, then libev will expect it to remedy the sitution, no
114matter what, when it returns. That is, libev will generally retry the 149matter what, when it returns. That is, libev will generally retry the
115requested operation, or, if the condition doesn't go away, do bad stuff 150requested operation, or, if the condition doesn't go away, do bad stuff
116(such as abort). 151(such as abort).
117 152
153Example: do the same thing as libev does internally:
154
155 static void
156 fatal_error (const char *msg)
157 {
158 perror (msg);
159 abort ();
160 }
161
162 ...
163 ev_set_syserr_cb (fatal_error);
164
118=back 165=back
119 166
120=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 167=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
121 168
122An event loop is described by a C<struct ev_loop *>. The library knows two 169An event loop is described by a C<struct ev_loop *>. The library knows two
… …
141 188
142If you don't know what event loop to use, use the one returned from this 189If you don't know what event loop to use, use the one returned from this
143function. 190function.
144 191
145The flags argument can be used to specify special behaviour or specific 192The flags argument can be used to specify special behaviour or specific
146backends to use, and is usually specified as C<0> (or EVFLAG_AUTO). 193backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
147 194
148It supports the following flags: 195The following flags are supported:
149 196
150=over 4 197=over 4
151 198
152=item C<EVFLAG_AUTO> 199=item C<EVFLAG_AUTO>
153 200
… …
189result in some caching, there is still a syscall per such incident 236result in some caching, there is still a syscall per such incident
190(because the fd could point to a different file description now), so its 237(because the fd could point to a different file description now), so its
191best to avoid that. Also, dup()ed file descriptors might not work very 238best to avoid that. Also, dup()ed file descriptors might not work very
192well if you register events for both fds. 239well if you register events for both fds.
193 240
241Please note that epoll sometimes generates spurious notifications, so you
242need to use non-blocking I/O or other means to avoid blocking when no data
243(or space) is available.
244
194=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones) 245=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
195 246
196Kqueue deserves special mention, as at the time of this writing, it 247Kqueue deserves special mention, as at the time of this writing, it
197was broken on all BSDs except NetBSD (usually it doesn't work with 248was broken on all BSDs except NetBSD (usually it doesn't work with
198anything but sockets and pipes, except on Darwin, where of course its 249anything but sockets and pipes, except on Darwin, where of course its
199completely useless). For this reason its not being "autodetected" unless 250completely useless). For this reason its not being "autodetected"
200you explicitly specify the flags (i.e. you don't use EVFLAG_AUTO). 251unless you explicitly specify it explicitly in the flags (i.e. using
252C<EVBACKEND_KQUEUE>).
201 253
202It scales in the same way as the epoll backend, but the interface to the 254It scales in the same way as the epoll backend, but the interface to the
203kernel is more efficient (which says nothing about its actual speed, of 255kernel is more efficient (which says nothing about its actual speed, of
204course). While starting and stopping an I/O watcher does not cause an 256course). While starting and stopping an I/O watcher does not cause an
205extra syscall as with epoll, it still adds up to four event changes per 257extra syscall as with epoll, it still adds up to four event changes per
… …
212=item C<EVBACKEND_PORT> (value 32, Solaris 10) 264=item C<EVBACKEND_PORT> (value 32, Solaris 10)
213 265
214This uses the Solaris 10 port mechanism. As with everything on Solaris, 266This uses the Solaris 10 port mechanism. As with everything on Solaris,
215it's really slow, but it still scales very well (O(active_fds)). 267it's really slow, but it still scales very well (O(active_fds)).
216 268
269Please note that solaris ports can result in a lot of spurious
270notifications, so you need to use non-blocking I/O or other means to avoid
271blocking when no data (or space) is available.
272
217=item C<EVBACKEND_ALL> 273=item C<EVBACKEND_ALL>
218 274
219Try all backends (even potentially broken ones that wouldn't be tried 275Try all backends (even potentially broken ones that wouldn't be tried
220with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 276with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
221C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 277C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
… …
225If one or more of these are ored into the flags value, then only these 281If one or more of these are ored into the flags value, then only these
226backends will be tried (in the reverse order as given here). If none are 282backends will be tried (in the reverse order as given here). If none are
227specified, most compiled-in backend will be tried, usually in reverse 283specified, most compiled-in backend will be tried, usually in reverse
228order of their flag values :) 284order of their flag values :)
229 285
286The most typical usage is like this:
287
288 if (!ev_default_loop (0))
289 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
290
291Restrict libev to the select and poll backends, and do not allow
292environment settings to be taken into account:
293
294 ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
295
296Use whatever libev has to offer, but make sure that kqueue is used if
297available (warning, breaks stuff, best use only with your own private
298event loop and only if you know the OS supports your types of fds):
299
300 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
301
230=item struct ev_loop *ev_loop_new (unsigned int flags) 302=item struct ev_loop *ev_loop_new (unsigned int flags)
231 303
232Similar to C<ev_default_loop>, but always creates a new event loop that is 304Similar to C<ev_default_loop>, but always creates a new event loop that is
233always distinct from the default loop. Unlike the default loop, it cannot 305always distinct from the default loop. Unlike the default loop, it cannot
234handle signal and child watchers, and attempts to do so will be greeted by 306handle signal and child watchers, and attempts to do so will be greeted by
235undefined behaviour (or a failed assertion if assertions are enabled). 307undefined behaviour (or a failed assertion if assertions are enabled).
236 308
309Example: try to create a event loop that uses epoll and nothing else.
310
311 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
312 if (!epoller)
313 fatal ("no epoll found here, maybe it hides under your chair");
314
237=item ev_default_destroy () 315=item ev_default_destroy ()
238 316
239Destroys the default loop again (frees all memory and kernel state 317Destroys the default loop again (frees all memory and kernel state
240etc.). This stops all registered event watchers (by not touching them in 318etc.). This stops all registered event watchers (by not touching them in
241any way whatsoever, although you cannot rely on this :). 319any way whatsoever, although you cannot rely on this :).
… …
278use. 356use.
279 357
280=item ev_tstamp ev_now (loop) 358=item ev_tstamp ev_now (loop)
281 359
282Returns the current "event loop time", which is the time the event loop 360Returns the current "event loop time", which is the time the event loop
283got events and started processing them. This timestamp does not change 361received events and started processing them. This timestamp does not
284as long as callbacks are being processed, and this is also the base time 362change as long as callbacks are being processed, and this is also the base
285used for relative timers. You can treat it as the timestamp of the event 363time used for relative timers. You can treat it as the timestamp of the
286occuring (or more correctly, the mainloop finding out about it). 364event occuring (or more correctly, libev finding out about it).
287 365
288=item ev_loop (loop, int flags) 366=item ev_loop (loop, int flags)
289 367
290Finally, this is it, the event handler. This function usually is called 368Finally, this is it, the event handler. This function usually is called
291after you initialised all your watchers and you want to start handling 369after you initialised all your watchers and you want to start handling
292events. 370events.
293 371
294If the flags argument is specified as 0, it will not return until either 372If the flags argument is specified as C<0>, it will not return until
295no event watchers are active anymore or C<ev_unloop> was called. 373either no event watchers are active anymore or C<ev_unloop> was called.
374
375Please note that an explicit C<ev_unloop> is usually better than
376relying on all watchers to be stopped when deciding when a program has
377finished (especially in interactive programs), but having a program that
378automatically loops as long as it has to and no longer by virtue of
379relying on its watchers stopping correctly is a thing of beauty.
296 380
297A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle 381A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
298those events and any outstanding ones, but will not block your process in 382those events and any outstanding ones, but will not block your process in
299case there are no events and will return after one iteration of the loop. 383case there are no events and will return after one iteration of the loop.
300 384
301A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if 385A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
302neccessary) and will handle those and any outstanding ones. It will block 386neccessary) and will handle those and any outstanding ones. It will block
303your process until at least one new event arrives, and will return after 387your process until at least one new event arrives, and will return after
304one iteration of the loop. 388one iteration of the loop. This is useful if you are waiting for some
389external event in conjunction with something not expressible using other
390libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
391usually a better approach for this kind of thing.
305 392
306This flags value could be used to implement alternative looping
307constructs, but the C<prepare> and C<check> watchers provide a better and
308more generic mechanism.
309
310Here are the gory details of what ev_loop does: 393Here are the gory details of what C<ev_loop> does:
311 394
312 1. If there are no active watchers (reference count is zero), return. 395 * If there are no active watchers (reference count is zero), return.
313 2. Queue and immediately call all prepare watchers. 396 - Queue prepare watchers and then call all outstanding watchers.
314 3. If we have been forked, recreate the kernel state. 397 - If we have been forked, recreate the kernel state.
315 4. Update the kernel state with all outstanding changes. 398 - Update the kernel state with all outstanding changes.
316 5. Update the "event loop time". 399 - Update the "event loop time".
317 6. Calculate for how long to block. 400 - Calculate for how long to block.
318 7. Block the process, waiting for events. 401 - Block the process, waiting for any events.
402 - Queue all outstanding I/O (fd) events.
319 8. Update the "event loop time" and do time jump handling. 403 - Update the "event loop time" and do time jump handling.
320 9. Queue all outstanding timers. 404 - Queue all outstanding timers.
321 10. Queue all outstanding periodics. 405 - Queue all outstanding periodics.
322 11. If no events are pending now, queue all idle watchers. 406 - If no events are pending now, queue all idle watchers.
323 12. Queue all check watchers. 407 - Queue all check watchers.
324 13. Call all queued watchers in reverse order (i.e. check watchers first). 408 - Call all queued watchers in reverse order (i.e. check watchers first).
409 Signals and child watchers are implemented as I/O watchers, and will
410 be handled here by queueing them when their watcher gets executed.
325 14. If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK 411 - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
326 was used, return, otherwise continue with step #1. 412 were used, return, otherwise continue with step *.
413
414Example: queue some jobs and then loop until no events are outsanding
415anymore.
416
417 ... queue jobs here, make sure they register event watchers as long
418 ... as they still have work to do (even an idle watcher will do..)
419 ev_loop (my_loop, 0);
420 ... jobs done. yeah!
327 421
328=item ev_unloop (loop, how) 422=item ev_unloop (loop, how)
329 423
330Can be used to make a call to C<ev_loop> return early (but only after it 424Can be used to make a call to C<ev_loop> return early (but only after it
331has processed all outstanding events). The C<how> argument must be either 425has processed all outstanding events). The C<how> argument must be either
… …
345visible to the libev user and should not keep C<ev_loop> from exiting if 439visible to the libev user and should not keep C<ev_loop> from exiting if
346no event watchers registered by it are active. It is also an excellent 440no event watchers registered by it are active. It is also an excellent
347way to do this for generic recurring timers or from within third-party 441way to do this for generic recurring timers or from within third-party
348libraries. Just remember to I<unref after start> and I<ref before stop>. 442libraries. Just remember to I<unref after start> and I<ref before stop>.
349 443
444Example: create a signal watcher, but keep it from keeping C<ev_loop>
445running when nothing else is active.
446
447 struct dv_signal exitsig;
448 ev_signal_init (&exitsig, sig_cb, SIGINT);
449 ev_signal_start (myloop, &exitsig);
450 evf_unref (myloop);
451
452Example: for some weird reason, unregister the above signal handler again.
453
454 ev_ref (myloop);
455 ev_signal_stop (myloop, &exitsig);
456
350=back 457=back
351 458
352=head1 ANATOMY OF A WATCHER 459=head1 ANATOMY OF A WATCHER
353 460
354A watcher is a structure that you create and register to record your 461A watcher is a structure that you create and register to record your
… …
495=head1 WATCHER TYPES 602=head1 WATCHER TYPES
496 603
497This section describes each watcher in detail, but will not repeat 604This section describes each watcher in detail, but will not repeat
498information given in the last section. 605information given in the last section.
499 606
607
500=head2 C<ev_io> - is this file descriptor readable or writable 608=head2 C<ev_io> - is this file descriptor readable or writable
501 609
502I/O watchers check whether a file descriptor is readable or writable 610I/O watchers check whether a file descriptor is readable or writable
503in each iteration of the event loop (This behaviour is called 611in each iteration of the event loop (This behaviour is called
504level-triggering because you keep receiving events as long as the 612level-triggering because you keep receiving events as long as the
… …
528 636
529Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive 637Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive
530events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ | 638events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ |
531EV_WRITE> to receive the given events. 639EV_WRITE> to receive the given events.
532 640
641Please note that most of the more scalable backend mechanisms (for example
642epoll and solaris ports) can result in spurious readyness notifications
643for file descriptors, so you practically need to use non-blocking I/O (and
644treat callback invocation as hint only), or retest separately with a safe
645interface before doing I/O (XLib can do this), or force the use of either
646C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>, which don't suffer from this
647problem. Also note that it is quite easy to have your callback invoked
648when the readyness condition is no longer valid even when employing
649typical ways of handling events, so its a good idea to use non-blocking
650I/O unconditionally.
651
533=back 652=back
653
654Example: call C<stdin_readable_cb> when STDIN_FILENO has become, well
655readable, but only once. Since it is likely line-buffered, you could
656attempt to read a whole line in the callback:
657
658 static void
659 stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
660 {
661 ev_io_stop (loop, w);
662 .. read from stdin here (or from w->fd) and haqndle any I/O errors
663 }
664
665 ...
666 struct ev_loop *loop = ev_default_init (0);
667 struct ev_io stdin_readable;
668 ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
669 ev_io_start (loop, &stdin_readable);
670 ev_loop (loop, 0);
671
534 672
535=head2 C<ev_timer> - relative and optionally recurring timeouts 673=head2 C<ev_timer> - relative and optionally recurring timeouts
536 674
537Timer watchers are simple relative timers that generate an event after a 675Timer watchers are simple relative timers that generate an event after a
538given time, and optionally repeating in regular intervals after that. 676given time, and optionally repeating in regular intervals after that.
… …
591state where you do not expect data to travel on the socket, you can stop 729state where you do not expect data to travel on the socket, you can stop
592the timer, and again will automatically restart it if need be. 730the timer, and again will automatically restart it if need be.
593 731
594=back 732=back
595 733
734Example: create a timer that fires after 60 seconds.
735
736 static void
737 one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
738 {
739 .. one minute over, w is actually stopped right here
740 }
741
742 struct ev_timer mytimer;
743 ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
744 ev_timer_start (loop, &mytimer);
745
746Example: create a timeout timer that times out after 10 seconds of
747inactivity.
748
749 static void
750 timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
751 {
752 .. ten seconds without any activity
753 }
754
755 struct ev_timer mytimer;
756 ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
757 ev_timer_again (&mytimer); /* start timer */
758 ev_loop (loop, 0);
759
760 // and in some piece of code that gets executed on any "activity":
761 // reset the timeout to start ticking again at 10 seconds
762 ev_timer_again (&mytimer);
763
764
596=head2 C<ev_periodic> - to cron or not to cron 765=head2 C<ev_periodic> - to cron or not to cron
597 766
598Periodic watchers are also timers of a kind, but they are very versatile 767Periodic watchers are also timers of a kind, but they are very versatile
599(and unfortunately a bit complex). 768(and unfortunately a bit complex).
600 769
… …
695a different time than the last time it was called (e.g. in a crond like 864a different time than the last time it was called (e.g. in a crond like
696program when the crontabs have changed). 865program when the crontabs have changed).
697 866
698=back 867=back
699 868
869Example: call a callback every hour, or, more precisely, whenever the
870system clock is divisible by 3600. The callback invocation times have
871potentially a lot of jittering, but good long-term stability.
872
873 static void
874 clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
875 {
876 ... its now a full hour (UTC, or TAI or whatever your clock follows)
877 }
878
879 struct ev_periodic hourly_tick;
880 ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
881 ev_periodic_start (loop, &hourly_tick);
882
883Example: the same as above, but use a reschedule callback to do it:
884
885 #include <math.h>
886
887 static ev_tstamp
888 my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
889 {
890 return fmod (now, 3600.) + 3600.;
891 }
892
893 ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
894
895Example: call a callback every hour, starting now:
896
897 struct ev_periodic hourly_tick;
898 ev_periodic_init (&hourly_tick, clock_cb,
899 fmod (ev_now (loop), 3600.), 3600., 0);
900 ev_periodic_start (loop, &hourly_tick);
901
902
700=head2 C<ev_signal> - signal me when a signal gets signalled 903=head2 C<ev_signal> - signal me when a signal gets signalled
701 904
702Signal watchers will trigger an event when the process receives a specific 905Signal watchers will trigger an event when the process receives a specific
703signal one or more times. Even though signals are very asynchronous, libev 906signal one or more times. Even though signals are very asynchronous, libev
704will try it's best to deliver signals synchronously, i.e. as part of the 907will try it's best to deliver signals synchronously, i.e. as part of the
… …
739the status word (use the macros from C<sys/wait.h> and see your systems 942the status word (use the macros from C<sys/wait.h> and see your systems
740C<waitpid> documentation). The C<rpid> member contains the pid of the 943C<waitpid> documentation). The C<rpid> member contains the pid of the
741process causing the status change. 944process causing the status change.
742 945
743=back 946=back
947
948Example: try to exit cleanly on SIGINT and SIGTERM.
949
950 static void
951 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
952 {
953 ev_unloop (loop, EVUNLOOP_ALL);
954 }
955
956 struct ev_signal signal_watcher;
957 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
958 ev_signal_start (loop, &sigint_cb);
959
744 960
745=head2 C<ev_idle> - when you've got nothing better to do 961=head2 C<ev_idle> - when you've got nothing better to do
746 962
747Idle watchers trigger events when there are no other events are pending 963Idle watchers trigger events when there are no other events are pending
748(prepare, check and other idle watchers do not count). That is, as long 964(prepare, check and other idle watchers do not count). That is, as long
… …
767Initialises and configures the idle watcher - it has no parameters of any 983Initialises and configures the idle watcher - it has no parameters of any
768kind. There is a C<ev_idle_set> macro, but using it is utterly pointless, 984kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
769believe me. 985believe me.
770 986
771=back 987=back
988
989Example: dynamically allocate an C<ev_idle>, start it, and in the
990callback, free it. Alos, use no error checking, as usual.
991
992 static void
993 idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
994 {
995 free (w);
996 // now do something you wanted to do when the program has
997 // no longer asnything immediate to do.
998 }
999
1000 struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1001 ev_idle_init (idle_watcher, idle_cb);
1002 ev_idle_start (loop, idle_cb);
1003
772 1004
773=head2 C<ev_prepare> and C<ev_check> - customise your event loop 1005=head2 C<ev_prepare> and C<ev_check> - customise your event loop
774 1006
775Prepare and check watchers are usually (but not always) used in tandem: 1007Prepare and check watchers are usually (but not always) used in tandem:
776prepare watchers get invoked before the process blocks and check watchers 1008prepare watchers get invoked before the process blocks and check watchers
… …
808parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set> 1040parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
809macros, but using them is utterly, utterly and completely pointless. 1041macros, but using them is utterly, utterly and completely pointless.
810 1042
811=back 1043=back
812 1044
1045Example: *TODO*.
1046
1047
813=head1 OTHER FUNCTIONS 1048=head1 OTHER FUNCTIONS
814 1049
815There are some other functions of possible interest. Described. Here. Now. 1050There are some other functions of possible interest. Described. Here. Now.
816 1051
817=over 4 1052=over 4
… …
863 1098
864Feed an event as if the given signal occured (loop must be the default loop!). 1099Feed an event as if the given signal occured (loop must be the default loop!).
865 1100
866=back 1101=back
867 1102
1103
868=head1 LIBEVENT EMULATION 1104=head1 LIBEVENT EMULATION
869 1105
870Libev offers a compatibility emulation layer for libevent. It cannot 1106Libev offers a compatibility emulation layer for libevent. It cannot
871emulate the internals of libevent, so here are some usage hints: 1107emulate the internals of libevent, so here are some usage hints:
872 1108

Diff Legend

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