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

Comparing libev/ev.pod (file contents):
Revision 1.30 by root, Fri Nov 23 04:36:03 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
89=item unsigned int ev_supported_backends ()
90
91Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
92value) compiled into this binary of libev (independent of their
93availability on the system you are running on). See C<ev_default_loop> for
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));
101
102=item unsigned int ev_recommended_backends ()
103
104Return the set of all backends compiled into this binary of libev and also
105recommended for this platform. This set is often smaller than the one
106returned by C<ev_supported_backends>, as for example kqueue is broken on
107most BSDs and will not be autodetected unless you explicitly request it
108(assuming you know what you are doing). This is the set of backends that
109libev will probe for if you specify no backends explicitly.
110
80=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 111=item ev_set_allocator (void *(*cb)(void *ptr, long size))
81 112
82Sets the allocation function to use (the prototype is similar to the 113Sets the allocation function to use (the prototype is similar to the
83realloc C function, the semantics are identical). It is used to allocate 114realloc C function, the semantics are identical). It is used to allocate
84and free memory (no surprises here). If it returns zero when memory 115and free memory (no surprises here). If it returns zero when memory
… …
86destructive action. The default is your system realloc function. 117destructive action. The default is your system realloc function.
87 118
88You could override this function in high-availability programs to, say, 119You could override this function in high-availability programs to, say,
89free 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,
90or 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);
91 142
92=item ev_set_syserr_cb (void (*cb)(const char *msg)); 143=item ev_set_syserr_cb (void (*cb)(const char *msg));
93 144
94Set the callback function to call on a retryable syscall error (such 145Set the callback function to call on a retryable syscall error (such
95as failed select, poll, epoll_wait). The message is a printable string 146as failed select, poll, epoll_wait). The message is a printable string
… …
97callback 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
98matter what, when it returns. That is, libev will generally retry the 149matter what, when it returns. That is, libev will generally retry the
99requested 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
100(such as abort). 151(such as abort).
101 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
102=back 165=back
103 166
104=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 167=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
105 168
106An 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
… …
119=item struct ev_loop *ev_default_loop (unsigned int flags) 182=item struct ev_loop *ev_default_loop (unsigned int flags)
120 183
121This will initialise the default event loop if it hasn't been initialised 184This will initialise the default event loop if it hasn't been initialised
122yet and return it. If the default loop could not be initialised, returns 185yet and return it. If the default loop could not be initialised, returns
123false. If it already was initialised it simply returns it (and ignores the 186false. If it already was initialised it simply returns it (and ignores the
124flags). 187flags. If that is troubling you, check C<ev_backend ()> afterwards).
125 188
126If 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
127function. 190function.
128 191
129The flags argument can be used to specify special behaviour or specific 192The flags argument can be used to specify special behaviour or specific
130backends to use, and is usually specified as 0 (or EVFLAG_AUTO). 193backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
131 194
132It supports the following flags: 195The following flags are supported:
133 196
134=over 4 197=over 4
135 198
136=item C<EVFLAG_AUTO> 199=item C<EVFLAG_AUTO>
137 200
… …
145C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 208C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
146override the flags completely if it is found in the environment. This is 209override the flags completely if it is found in the environment. This is
147useful to try out specific backends to test their performance, or to work 210useful to try out specific backends to test their performance, or to work
148around bugs. 211around bugs.
149 212
150=item C<EVMETHOD_SELECT> (value 1, portable select backend) 213=item C<EVBACKEND_SELECT> (value 1, portable select backend)
151 214
152This is your standard select(2) backend. Not I<completely> standard, as 215This is your standard select(2) backend. Not I<completely> standard, as
153libev tries to roll its own fd_set with no limits on the number of fds, 216libev tries to roll its own fd_set with no limits on the number of fds,
154but if that fails, expect a fairly low limit on the number of fds when 217but if that fails, expect a fairly low limit on the number of fds when
155using this backend. It doesn't scale too well (O(highest_fd)), but its usually 218using this backend. It doesn't scale too well (O(highest_fd)), but its usually
156the fastest backend for a low number of fds. 219the fastest backend for a low number of fds.
157 220
158=item C<EVMETHOD_POLL> (value 2, poll backend, available everywhere except on windows) 221=item C<EVBACKEND_POLL> (value 2, poll backend, available everywhere except on windows)
159 222
160And this is your standard poll(2) backend. It's more complicated than 223And this is your standard poll(2) backend. It's more complicated than
161select, but handles sparse fds better and has no artificial limit on the 224select, but handles sparse fds better and has no artificial limit on the
162number of fds you can use (except it will slow down considerably with a 225number of fds you can use (except it will slow down considerably with a
163lot of inactive fds). It scales similarly to select, i.e. O(total_fds). 226lot of inactive fds). It scales similarly to select, i.e. O(total_fds).
164 227
165=item C<EVMETHOD_EPOLL> (value 4, Linux) 228=item C<EVBACKEND_EPOLL> (value 4, Linux)
166 229
167For few fds, this backend is a bit little slower than poll and select, 230For few fds, this backend is a bit little slower than poll and select,
168but it scales phenomenally better. While poll and select usually scale like 231but it scales phenomenally better. While poll and select usually scale like
169O(total_fds) where n is the total number of fds (or the highest fd), epoll scales 232O(total_fds) where n is the total number of fds (or the highest fd), epoll scales
170either O(1) or O(active_fds). 233either O(1) or O(active_fds).
… …
173result in some caching, there is still a syscall per such incident 236result in some caching, there is still a syscall per such incident
174(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
175best 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
176well if you register events for both fds. 239well if you register events for both fds.
177 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
178=item C<EVMETHOD_KQUEUE> (value 8, most BSD clones) 245=item C<EVBACKEND_KQUEUE> (value 8, most BSD clones)
179 246
180Kqueue deserves special mention, as at the time of this writing, it 247Kqueue deserves special mention, as at the time of this writing, it
181was 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
182anything but sockets and pipes, except on Darwin, where of course its 249anything but sockets and pipes, except on Darwin, where of course its
183completely useless). For this reason its not being "autodetected" unless 250completely useless). For this reason its not being "autodetected"
184you 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>).
185 253
186It 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
187kernel is more efficient (which says nothing about its actual speed, of 255kernel is more efficient (which says nothing about its actual speed, of
188course). 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
189extra 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
190incident, so its best to avoid that. 258incident, so its best to avoid that.
191 259
192=item C<EVMETHOD_DEVPOLL> (value 16, Solaris 8) 260=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
193 261
194This is not implemented yet (and might never be). 262This is not implemented yet (and might never be).
195 263
196=item C<EVMETHOD_PORT> (value 32, Solaris 10) 264=item C<EVBACKEND_PORT> (value 32, Solaris 10)
197 265
198This uses the Solaris 10 port mechanism. As with everything on Solaris, 266This uses the Solaris 10 port mechanism. As with everything on Solaris,
199it'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)).
200 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
201=item C<EVMETHOD_ALL> 273=item C<EVBACKEND_ALL>
202 274
203Try all backends (even potentially broken ones that wouldn't be tried 275Try all backends (even potentially broken ones that wouldn't be tried
204with 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
205C<EVMETHOD_ALL & ~EVMETHOD_KQUEUE>. 277C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
206 278
207=back 279=back
208 280
209If 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
210backends 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
211specified, most compiled-in backend will be tried, usually in reverse 283specified, most compiled-in backend will be tried, usually in reverse
212order of their flag values :) 284order of their flag values :)
213 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
214=item struct ev_loop *ev_loop_new (unsigned int flags) 302=item struct ev_loop *ev_loop_new (unsigned int flags)
215 303
216Similar 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
217always distinct from the default loop. Unlike the default loop, it cannot 305always distinct from the default loop. Unlike the default loop, it cannot
218handle 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
219undefined behaviour (or a failed assertion if assertions are enabled). 307undefined behaviour (or a failed assertion if assertions are enabled).
220 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
221=item ev_default_destroy () 315=item ev_default_destroy ()
222 316
223Destroys the default loop again (frees all memory and kernel state 317Destroys the default loop again (frees all memory and kernel state
224etc.). This stops all registered event watchers (by not touching them in 318etc.). This stops all registered event watchers (by not touching them in
225any way whatsoever, although you cannot rely on this :). 319any way whatsoever, although you cannot rely on this :).
… …
244it just in case after a fork. To make this easy, the function will fit in 338it just in case after a fork. To make this easy, the function will fit in
245quite nicely into a call to C<pthread_atfork>: 339quite nicely into a call to C<pthread_atfork>:
246 340
247 pthread_atfork (0, 0, ev_default_fork); 341 pthread_atfork (0, 0, ev_default_fork);
248 342
343At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
344without calling this function, so if you force one of those backends you
345do not need to care.
346
249=item ev_loop_fork (loop) 347=item ev_loop_fork (loop)
250 348
251Like C<ev_default_fork>, but acts on an event loop created by 349Like C<ev_default_fork>, but acts on an event loop created by
252C<ev_loop_new>. Yes, you have to call this on every allocated event loop 350C<ev_loop_new>. Yes, you have to call this on every allocated event loop
253after fork, and how you do this is entirely your own problem. 351after fork, and how you do this is entirely your own problem.
254 352
255=item unsigned int ev_method (loop) 353=item unsigned int ev_backend (loop)
256 354
257Returns one of the C<EVMETHOD_*> flags indicating the event backend in 355Returns one of the C<EVBACKEND_*> flags indicating the event backend in
258use. 356use.
259 357
260=item ev_tstamp ev_now (loop) 358=item ev_tstamp ev_now (loop)
261 359
262Returns 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
263got events and started processing them. This timestamp does not change 361received events and started processing them. This timestamp does not
264as 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
265used 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
266occuring (or more correctly, the mainloop finding out about it). 364event occuring (or more correctly, libev finding out about it).
267 365
268=item ev_loop (loop, int flags) 366=item ev_loop (loop, int flags)
269 367
270Finally, this is it, the event handler. This function usually is called 368Finally, this is it, the event handler. This function usually is called
271after you initialised all your watchers and you want to start handling 369after you initialised all your watchers and you want to start handling
272events. 370events.
273 371
274If 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
275no 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.
276 380
277A 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
278those 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
279case 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.
280 384
281A 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
282neccessary) and will handle those and any outstanding ones. It will block 386neccessary) and will handle those and any outstanding ones. It will block
283your 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
284one 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.
285 392
286This flags value could be used to implement alternative looping
287constructs, but the C<prepare> and C<check> watchers provide a better and
288more generic mechanism.
289
290Here are the gory details of what ev_loop does: 393Here are the gory details of what C<ev_loop> does:
291 394
292 1. If there are no active watchers (reference count is zero), return. 395 * If there are no active watchers (reference count is zero), return.
293 2. Queue and immediately call all prepare watchers. 396 - Queue prepare watchers and then call all outstanding watchers.
294 3. If we have been forked, recreate the kernel state. 397 - If we have been forked, recreate the kernel state.
295 4. Update the kernel state with all outstanding changes. 398 - Update the kernel state with all outstanding changes.
296 5. Update the "event loop time". 399 - Update the "event loop time".
297 6. Calculate for how long to block. 400 - Calculate for how long to block.
298 7. Block the process, waiting for events. 401 - Block the process, waiting for any events.
402 - Queue all outstanding I/O (fd) events.
299 8. Update the "event loop time" and do time jump handling. 403 - Update the "event loop time" and do time jump handling.
300 9. Queue all outstanding timers. 404 - Queue all outstanding timers.
301 10. Queue all outstanding periodics. 405 - Queue all outstanding periodics.
302 11. If no events are pending now, queue all idle watchers. 406 - If no events are pending now, queue all idle watchers.
303 12. Queue all check watchers. 407 - Queue all check watchers.
304 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.
305 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
306 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!
307 421
308=item ev_unloop (loop, how) 422=item ev_unloop (loop, how)
309 423
310Can 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
311has processed all outstanding events). The C<how> argument must be either 425has processed all outstanding events). The C<how> argument must be either
… …
325visible 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
326no 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
327way 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
328libraries. 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>.
329 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
330=back 457=back
331 458
332=head1 ANATOMY OF A WATCHER 459=head1 ANATOMY OF A WATCHER
333 460
334A 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
… …
368*) >>), and you can stop watching for events at any time by calling the 495*) >>), and you can stop watching for events at any time by calling the
369corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>. 496corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
370 497
371As long as your watcher is active (has been started but not stopped) you 498As long as your watcher is active (has been started but not stopped) you
372must not touch the values stored in it. Most specifically you must never 499must not touch the values stored in it. Most specifically you must never
373reinitialise it or call its set method. 500reinitialise it or call its set macro.
374 501
375You can check whether an event is active by calling the C<ev_is_active 502You can check whether an event is active by calling the C<ev_is_active
376(watcher *)> macro. To see whether an event is outstanding (but the 503(watcher *)> macro. To see whether an event is outstanding (but the
377callback for it has not been called yet) you can use the C<ev_is_pending 504callback for it has not been called yet) you can use the C<ev_is_pending
378(watcher *)> macro. 505(watcher *)> macro.
… …
475=head1 WATCHER TYPES 602=head1 WATCHER TYPES
476 603
477This section describes each watcher in detail, but will not repeat 604This section describes each watcher in detail, but will not repeat
478information given in the last section. 605information given in the last section.
479 606
607
480=head2 C<ev_io> - is this file descriptor readable or writable 608=head2 C<ev_io> - is this file descriptor readable or writable
481 609
482I/O watchers check whether a file descriptor is readable or writable 610I/O watchers check whether a file descriptor is readable or writable
483in each iteration of the event loop (This behaviour is called 611in each iteration of the event loop (This behaviour is called
484level-triggering because you keep receiving events as long as the 612level-triggering because you keep receiving events as long as the
… …
495descriptors correctly if you register interest in two or more fds pointing 623descriptors correctly if you register interest in two or more fds pointing
496to the same underlying file/socket etc. description (that is, they share 624to the same underlying file/socket etc. description (that is, they share
497the same underlying "file open"). 625the same underlying "file open").
498 626
499If you must do this, then force the use of a known-to-be-good backend 627If you must do this, then force the use of a known-to-be-good backend
500(at the time of this writing, this includes only EVMETHOD_SELECT and 628(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
501EVMETHOD_POLL). 629C<EVBACKEND_POLL>).
502 630
503=over 4 631=over 4
504 632
505=item ev_io_init (ev_io *, callback, int fd, int events) 633=item ev_io_init (ev_io *, callback, int fd, int events)
506 634
… …
508 636
509Configures 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
510events 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 |
511EV_WRITE> to receive the given events. 639EV_WRITE> to receive the given events.
512 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
513=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
514 672
515=head2 C<ev_timer> - relative and optionally recurring timeouts 673=head2 C<ev_timer> - relative and optionally recurring timeouts
516 674
517Timer watchers are simple relative timers that generate an event after a 675Timer watchers are simple relative timers that generate an event after a
518given time, and optionally repeating in regular intervals after that. 676given time, and optionally repeating in regular intervals after that.
… …
571state 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
572the timer, and again will automatically restart it if need be. 730the timer, and again will automatically restart it if need be.
573 731
574=back 732=back
575 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
576=head2 C<ev_periodic> - to cron or not to cron 765=head2 C<ev_periodic> - to cron or not to cron
577 766
578Periodic 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
579(and unfortunately a bit complex). 768(and unfortunately a bit complex).
580 769
… …
675a 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
676program when the crontabs have changed). 865program when the crontabs have changed).
677 866
678=back 867=back
679 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
680=head2 C<ev_signal> - signal me when a signal gets signalled 903=head2 C<ev_signal> - signal me when a signal gets signalled
681 904
682Signal watchers will trigger an event when the process receives a specific 905Signal watchers will trigger an event when the process receives a specific
683signal one or more times. Even though signals are very asynchronous, libev 906signal one or more times. Even though signals are very asynchronous, libev
684will 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
… …
719the 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
720C<waitpid> documentation). The C<rpid> member contains the pid of the 943C<waitpid> documentation). The C<rpid> member contains the pid of the
721process causing the status change. 944process causing the status change.
722 945
723=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
724 960
725=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
726 962
727Idle watchers trigger events when there are no other events are pending 963Idle watchers trigger events when there are no other events are pending
728(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
… …
747Initialises and configures the idle watcher - it has no parameters of any 983Initialises and configures the idle watcher - it has no parameters of any
748kind. 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,
749believe me. 985believe me.
750 986
751=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
752 1004
753=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
754 1006
755Prepare and check watchers are usually (but not always) used in tandem: 1007Prepare and check watchers are usually (but not always) used in tandem:
756prepare watchers get invoked before the process blocks and check watchers 1008prepare watchers get invoked before the process blocks and check watchers
… …
788parameters 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>
789macros, but using them is utterly, utterly and completely pointless. 1041macros, but using them is utterly, utterly and completely pointless.
790 1042
791=back 1043=back
792 1044
1045Example: *TODO*.
1046
1047
793=head1 OTHER FUNCTIONS 1048=head1 OTHER FUNCTIONS
794 1049
795There are some other functions of possible interest. Described. Here. Now. 1050There are some other functions of possible interest. Described. Here. Now.
796 1051
797=over 4 1052=over 4
… …
843 1098
844Feed 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!).
845 1100
846=back 1101=back
847 1102
1103
848=head1 LIBEVENT EMULATION 1104=head1 LIBEVENT EMULATION
849 1105
850Libev offers a compatibility emulation layer for libevent. It cannot 1106Libev offers a compatibility emulation layer for libevent. It cannot
851emulate the internals of libevent, so here are some usage hints: 1107emulate the internals of libevent, so here are some usage hints:
852 1108

Diff Legend

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