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

Comparing libev/ev.pod (file contents):
Revision 1.416 by root, Sun May 6 13:42:10 2012 UTC vs.
Revision 1.446 by root, Mon Mar 18 19:28:15 2019 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
263 265
264You could override this function in high-availability programs to, say, 266You could override this function in high-availability programs to, say,
265free some memory if it cannot allocate memory, to use a special allocator, 267free some memory if it cannot allocate memory, to use a special allocator,
266or even to sleep a while and retry until some memory is available. 268or even to sleep a while and retry until some memory is available.
267 269
270Example: The following is the C<realloc> function that libev itself uses
271which should work with C<realloc> and C<free> functions of all kinds and
272is probably a good basis for your own implementation.
273
274 static void *
275 ev_realloc_emul (void *ptr, long size) EV_NOEXCEPT
276 {
277 if (size)
278 return realloc (ptr, size);
279
280 free (ptr);
281 return 0;
282 }
283
268Example: Replace the libev allocator with one that waits a bit and then 284Example: Replace the libev allocator with one that waits a bit and then
269retries (example requires a standards-compliant C<realloc>). 285retries.
270 286
271 static void * 287 static void *
272 persistent_realloc (void *ptr, size_t size) 288 persistent_realloc (void *ptr, size_t size)
273 { 289 {
290 if (!size)
291 {
292 free (ptr);
293 return 0;
294 }
295
274 for (;;) 296 for (;;)
275 { 297 {
276 void *newptr = realloc (ptr, size); 298 void *newptr = realloc (ptr, size);
277 299
278 if (newptr) 300 if (newptr)
396 418
397If this flag bit is or'ed into the flag value (or the program runs setuid 419If 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 420or setgid) then libev will I<not> look at the environment variable
399C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 421C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
400override the flags completely if it is found in the environment. This is 422override 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 423useful to try out specific backends to test their performance, to work
402around bugs. 424around bugs, or to make libev threadsafe (accessing environment variables
425cannot be done in a threadsafe way, but usually it works if no other
426thread modifies them).
403 427
404=item C<EVFLAG_FORKCHECK> 428=item C<EVFLAG_FORKCHECK>
405 429
406Instead of calling C<ev_loop_fork> manually after a fork, you can also 430Instead 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. 431make libev check for a fork in each iteration by enabling this flag.
408 432
409This works by calling C<getpid ()> on every iteration of the loop, 433This works by calling C<getpid ()> on every iteration of the loop,
410and thus this might slow down your event loop if you do a lot of loop 434and thus this might slow down your event loop if you do a lot of loop
411iterations and little real work, but is usually not noticeable (on my 435iterations and little real work, but is usually not noticeable (on my
412GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 436GNU/Linux system for example, C<getpid> is actually a simple 5-insn
413without a system call and thus I<very> fast, but my GNU/Linux system also has 437sequence without a system call and thus I<very> fast, but my GNU/Linux
414C<pthread_atfork> which is even faster). 438system also has C<pthread_atfork> which is even faster). (Update: glibc
439versions 2.25 apparently removed the C<getpid> optimisation again).
415 440
416The big advantage of this flag is that you can forget about fork (and 441The big advantage of this flag is that you can forget about fork (and
417forget about forgetting to tell libev about forking) when you use this 442forget about forgetting to tell libev about forking, although you still
418flag. 443have to ignore C<SIGPIPE>) when you use this flag.
419 444
420This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 445This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
421environment variable. 446environment variable.
422 447
423=item C<EVFLAG_NOINOTIFY> 448=item C<EVFLAG_NOINOTIFY>
569kernel is more efficient (which says nothing about its actual speed, of 594kernel is more efficient (which says nothing about its actual speed, of
570course). While stopping, setting and starting an I/O watcher does never 595course). 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 596cause 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 597two 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 598might 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 599drops fds silently in similarly hard-to-detect cases.
575 600
576This backend usually performs well under most conditions. 601This backend usually performs well under most conditions.
577 602
578While nominally embeddable in other event loops, this doesn't work 603While nominally embeddable in other event loops, this doesn't work
579everywhere, so you might need to test for this. And since it is broken 604everywhere, so you might need to test for this. And since it is broken
678If you need dynamically allocated loops it is better to use C<ev_loop_new> 703If you need dynamically allocated loops it is better to use C<ev_loop_new>
679and C<ev_loop_destroy>. 704and C<ev_loop_destroy>.
680 705
681=item ev_loop_fork (loop) 706=item ev_loop_fork (loop)
682 707
683This function sets a flag that causes subsequent C<ev_run> iterations to 708This function sets a flag that causes subsequent C<ev_run> iterations
684reinitialise the kernel state for backends that have one. Despite the 709to reinitialise the kernel state for backends that have one. Despite
685name, you can call it anytime, but it makes most sense after forking, in 710the name, you can call it anytime you are allowed to start or stop
686the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the 711watchers (except inside an C<ev_prepare> callback), but it makes most
712sense after forking, in the child process. You I<must> call it (or use
687child before resuming or calling C<ev_run>. 713C<EVFLAG_FORKCHECK>) in the child before resuming or calling C<ev_run>.
688 714
715In addition, if you want to reuse a loop (via this function or
716C<EVFLAG_FORKCHECK>), you I<also> have to ignore C<SIGPIPE>.
717
689Again, you I<have> to call it on I<any> loop that you want to re-use after 718Again, 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 719a 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 720because some kernel interfaces *cough* I<kqueue> *cough* do funny things
692during fork. 721during fork.
693 722
694On the other hand, you only need to call this function in the child 723On the other hand, you only need to call this function in the child
1393transition between them will be described in more detail - and while these 1422transition between them will be described in more detail - and while these
1394rules might look complicated, they usually do "the right thing". 1423rules might look complicated, they usually do "the right thing".
1395 1424
1396=over 4 1425=over 4
1397 1426
1398=item initialiased 1427=item initialised
1399 1428
1400Before a watcher can be registered with the event loop it has to be 1429Before 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 1430initialised. 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. 1431C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
1403 1432
2024 2053
2025The relative timeouts are calculated relative to the C<ev_now ()> 2054The relative timeouts are calculated relative to the C<ev_now ()>
2026time. This is usually the right thing as this timestamp refers to the time 2055time. This is usually the right thing as this timestamp refers to the time
2027of the event triggering whatever timeout you are modifying/starting. If 2056of the event triggering whatever timeout you are modifying/starting. If
2028you suspect event processing to be delayed and you I<need> to base the 2057you suspect event processing to be delayed and you I<need> to base the
2029timeout on the current time, use something like this to adjust for this: 2058timeout on the current time, use something like the following to adjust
2059for it:
2030 2060
2031 ev_timer_set (&timer, after + ev_now () - ev_time (), 0.); 2061 ev_timer_set (&timer, after + (ev_time () - ev_now ()), 0.);
2032 2062
2033If the event loop is suspended for a long time, you can also force an 2063If the event loop is suspended for a long time, you can also force an
2034update of the time returned by C<ev_now ()> by calling C<ev_now_update 2064update of the time returned by C<ev_now ()> by calling C<ev_now_update
2035()>. 2065()>, although that will push the event time of all outstanding events
2066further into the future.
2036 2067
2037=head3 The special problem of unsynchronised clocks 2068=head3 The special problem of unsynchronised clocks
2038 2069
2039Modern systems have a variety of clocks - libev itself uses the normal 2070Modern systems have a variety of clocks - libev itself uses the normal
2040"wall clock" clock and, if available, the monotonic clock (to avoid time 2071"wall clock" clock and, if available, the monotonic clock (to avoid time
2103 2134
2104=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat) 2135=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
2105 2136
2106=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat) 2137=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
2107 2138
2108Configure the timer to trigger after C<after> seconds. If C<repeat> 2139Configure the timer to trigger after C<after> seconds (fractional and
2109is C<0.>, then it will automatically be stopped once the timeout is 2140negative values are supported). If C<repeat> is C<0.>, then it will
2110reached. If it is positive, then the timer will automatically be 2141automatically be stopped once the timeout is reached. If it is positive,
2111configured to trigger again C<repeat> seconds later, again, and again, 2142then the timer will automatically be configured to trigger again C<repeat>
2112until stopped manually. 2143seconds later, again, and again, until stopped manually.
2113 2144
2114The timer itself will do a best-effort at avoiding drift, that is, if 2145The timer itself will do a best-effort at avoiding drift, that is, if
2115you configure a timer to trigger every 10 seconds, then it will normally 2146you configure a timer to trigger every 10 seconds, then it will normally
2116trigger at exactly 10 second intervals. If, however, your program cannot 2147trigger at exactly 10 second intervals. If, however, your program cannot
2117keep up with the timer (because it takes longer than those 10 seconds to 2148keep up with the timer (because it takes longer than those 10 seconds to
2199Periodic watchers are also timers of a kind, but they are very versatile 2230Periodic watchers are also timers of a kind, but they are very versatile
2200(and unfortunately a bit complex). 2231(and unfortunately a bit complex).
2201 2232
2202Unlike C<ev_timer>, periodic watchers are not based on real time (or 2233Unlike C<ev_timer>, periodic watchers are not based on real time (or
2203relative time, the physical time that passes) but on wall clock time 2234relative time, the physical time that passes) but on wall clock time
2204(absolute time, the thing you can read on your calender or clock). The 2235(absolute time, the thing you can read on your calendar or clock). The
2205difference is that wall clock time can run faster or slower than real 2236difference is that wall clock time can run faster or slower than real
2206time, and time jumps are not uncommon (e.g. when you adjust your 2237time, and time jumps are not uncommon (e.g. when you adjust your
2207wrist-watch). 2238wrist-watch).
2208 2239
2209You can tell a periodic watcher to trigger after some specific point 2240You can tell a periodic watcher to trigger after some specific point
2214C<ev_timer>, which would still trigger roughly 10 seconds after starting 2245C<ev_timer>, which would still trigger roughly 10 seconds after starting
2215it, as it uses a relative timeout). 2246it, as it uses a relative timeout).
2216 2247
2217C<ev_periodic> watchers can also be used to implement vastly more complex 2248C<ev_periodic> watchers can also be used to implement vastly more complex
2218timers, such as triggering an event on each "midnight, local time", or 2249timers, such as triggering an event on each "midnight, local time", or
2219other complicated rules. This cannot be done with C<ev_timer> watchers, as 2250other complicated rules. This cannot easily be done with C<ev_timer>
2220those cannot react to time jumps. 2251watchers, as those cannot react to time jumps.
2221 2252
2222As with timers, the callback is guaranteed to be invoked only when the 2253As with timers, the callback is guaranteed to be invoked only when the
2223point in time where it is supposed to trigger has passed. If multiple 2254point in time where it is supposed to trigger has passed. If multiple
2224timers become ready during the same loop iteration then the ones with 2255timers become ready during the same loop iteration then the ones with
2225earlier time-out values are invoked before ones with later time-out values 2256earlier time-out values are invoked before ones with later time-out values
2311 2342
2312NOTE: I<< This callback must always return a time that is higher than or 2343NOTE: I<< This callback must always return a time that is higher than or
2313equal to the passed C<now> value >>. 2344equal to the passed C<now> value >>.
2314 2345
2315This can be used to create very complex timers, such as a timer that 2346This can be used to create very complex timers, such as a timer that
2316triggers on "next midnight, local time". To do this, you would calculate the 2347triggers on "next midnight, local time". To do this, you would calculate
2317next midnight after C<now> and return the timestamp value for this. How 2348the next midnight after C<now> and return the timestamp value for
2318you do this is, again, up to you (but it is not trivial, which is the main 2349this. Here is a (completely untested, no error checking) example on how to
2319reason I omitted it as an example). 2350do this:
2351
2352 #include <time.h>
2353
2354 static ev_tstamp
2355 my_rescheduler (ev_periodic *w, ev_tstamp now)
2356 {
2357 time_t tnow = (time_t)now;
2358 struct tm tm;
2359 localtime_r (&tnow, &tm);
2360
2361 tm.tm_sec = tm.tm_min = tm.tm_hour = 0; // midnight current day
2362 ++tm.tm_mday; // midnight next day
2363
2364 return mktime (&tm);
2365 }
2366
2367Note: this code might run into trouble on days that have more then two
2368midnights (beginning and end).
2320 2369
2321=back 2370=back
2322 2371
2323=item ev_periodic_again (loop, ev_periodic *) 2372=item ev_periodic_again (loop, ev_periodic *)
2324 2373
2389 2438
2390 ev_periodic hourly_tick; 2439 ev_periodic hourly_tick;
2391 ev_periodic_init (&hourly_tick, clock_cb, 2440 ev_periodic_init (&hourly_tick, clock_cb,
2392 fmod (ev_now (loop), 3600.), 3600., 0); 2441 fmod (ev_now (loop), 3600.), 3600., 0);
2393 ev_periodic_start (loop, &hourly_tick); 2442 ev_periodic_start (loop, &hourly_tick);
2394 2443
2395 2444
2396=head2 C<ev_signal> - signal me when a signal gets signalled! 2445=head2 C<ev_signal> - signal me when a signal gets signalled!
2397 2446
2398Signal watchers will trigger an event when the process receives a specific 2447Signal watchers will trigger an event when the process receives a specific
2399signal one or more times. Even though signals are very asynchronous, libev 2448signal one or more times. Even though signals are very asynchronous, libev
2409only within the same loop, i.e. you can watch for C<SIGINT> in your 2458only 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 2459default 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 2460C<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. 2461the moment, C<SIGCHLD> is permanently tied to the default loop.
2413 2462
2414When the first watcher gets started will libev actually register something 2463Only 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 2464register something with the kernel. It thus coexists with your own signal
2416you don't register any with libev for the same signal). 2465handlers as long as you don't register any with libev for the same signal.
2417 2466
2418If possible and supported, libev will install its handlers with 2467If possible and supported, libev will install its handlers with
2419C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2468C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2420not be unduly interrupted. If you have a problem with system calls getting 2469not 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 2470interrupted by signals you can block all signals in an C<ev_check> watcher
2606 2655
2607=head2 C<ev_stat> - did the file attributes just change? 2656=head2 C<ev_stat> - did the file attributes just change?
2608 2657
2609This watches a file system path for attribute changes. That is, it calls 2658This 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) 2659C<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 2660and sees if it changed compared to the last time, invoking the callback
2612it did. 2661if it did. Starting the watcher C<stat>'s the file, so only changes that
2662happen after the watcher has been started will be reported.
2613 2663
2614The path does not need to exist: changing from "path exists" to "path does 2664The 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 2665not 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 2666exist" (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 2667C<st_nlink> field being zero (which is otherwise always forced to be at
2902 2952
2903Prepare and check watchers are often (but not always) used in pairs: 2953Prepare and check watchers are often (but not always) used in pairs:
2904prepare watchers get invoked before the process blocks and check watchers 2954prepare watchers get invoked before the process blocks and check watchers
2905afterwards. 2955afterwards.
2906 2956
2907You I<must not> call C<ev_run> or similar functions that enter 2957You I<must not> call C<ev_run> (or similar functions that enter the
2908the current event loop from either C<ev_prepare> or C<ev_check> 2958current event loop) or C<ev_loop_fork> from either C<ev_prepare> or
2909watchers. Other loops than the current one are fine, however. The 2959C<ev_check> watchers. Other loops than the current one are fine,
2910rationale behind this is that you do not need to check for recursion in 2960however. The rationale behind this is that you do not need to check
2911those watchers, i.e. the sequence will always be C<ev_prepare>, blocking, 2961for recursion in those watchers, i.e. the sequence will always be
2912C<ev_check> so if you have one watcher of each kind they will always be 2962C<ev_prepare>, blocking, C<ev_check> so if you have one watcher of each
2913called in pairs bracketing the blocking call. 2963kind they will always be called in pairs bracketing the blocking call.
2914 2964
2915Their main purpose is to integrate other event mechanisms into libev and 2965Their main purpose is to integrate other event mechanisms into libev and
2916their use is somewhat advanced. They could be used, for example, to track 2966their use is somewhat advanced. They could be used, for example, to track
2917variable changes, implement your own watchers, integrate net-snmp or a 2967variable changes, implement your own watchers, integrate net-snmp or a
2918coroutine library and lots more. They are also occasionally useful if 2968coroutine library and lots more. They are also occasionally useful if
2962 3012
2963Using an C<ev_check> watcher is almost enough: it will be called on the 3013Using an C<ev_check> watcher is almost enough: it will be called on the
2964next event loop iteration. However, that isn't as soon as possible - 3014next event loop iteration. However, that isn't as soon as possible -
2965without external events, your C<ev_check> watcher will not be invoked. 3015without external events, your C<ev_check> watcher will not be invoked.
2966 3016
2967
2968This is where C<ev_idle> watchers come in handy - all you need is a 3017This is where C<ev_idle> watchers come in handy - all you need is a
2969single global idle watcher that is active as long as you have one active 3018single global idle watcher that is active as long as you have one active
2970C<ev_check> watcher. The C<ev_idle> watcher makes sure the event loop 3019C<ev_check> watcher. The C<ev_idle> watcher makes sure the event loop
2971will not sleep, and the C<ev_check> watcher makes sure a callback gets 3020will not sleep, and the C<ev_check> watcher makes sure a callback gets
2972invoked. Neither watcher alone can do that. 3021invoked. Neither watcher alone can do that.
3178 3227
3179=over 4 3228=over 4
3180 3229
3181=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop) 3230=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
3182 3231
3183=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop) 3232=item ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)
3184 3233
3185Configures the watcher to embed the given loop, which must be 3234Configures the watcher to embed the given loop, which must be
3186embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be 3235embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
3187invoked automatically, otherwise it is the responsibility of the callback 3236invoked automatically, otherwise it is the responsibility of the callback
3188to invoke it (it will continue to be called until the sweep has been done, 3237to invoke it (it will continue to be called until the sweep has been done,
3209used). 3258used).
3210 3259
3211 struct ev_loop *loop_hi = ev_default_init (0); 3260 struct ev_loop *loop_hi = ev_default_init (0);
3212 struct ev_loop *loop_lo = 0; 3261 struct ev_loop *loop_lo = 0;
3213 ev_embed embed; 3262 ev_embed embed;
3214 3263
3215 // see if there is a chance of getting one that works 3264 // see if there is a chance of getting one that works
3216 // (remember that a flags value of 0 means autodetection) 3265 // (remember that a flags value of 0 means autodetection)
3217 loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3266 loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
3218 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3267 ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
3219 : 0; 3268 : 0;
3233C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too). 3282C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
3234 3283
3235 struct ev_loop *loop = ev_default_init (0); 3284 struct ev_loop *loop = ev_default_init (0);
3236 struct ev_loop *loop_socket = 0; 3285 struct ev_loop *loop_socket = 0;
3237 ev_embed embed; 3286 ev_embed embed;
3238 3287
3239 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3288 if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
3240 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3289 if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
3241 { 3290 {
3242 ev_embed_init (&embed, 0, loop_socket); 3291 ev_embed_init (&embed, 0, loop_socket);
3243 ev_embed_start (loop, &embed); 3292 ev_embed_start (loop, &embed);
3251 3300
3252=head2 C<ev_fork> - the audacity to resume the event loop after a fork 3301=head2 C<ev_fork> - the audacity to resume the event loop after a fork
3253 3302
3254Fork watchers are called when a C<fork ()> was detected (usually because 3303Fork watchers are called when a C<fork ()> was detected (usually because
3255whoever is a good citizen cared to tell libev about it by calling 3304whoever is a good citizen cared to tell libev about it by calling
3256C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the 3305C<ev_loop_fork>). The invocation is done before the event loop blocks next
3257event loop blocks next and before C<ev_check> watchers are being called, 3306and before C<ev_check> watchers are being called, and only in the child
3258and only in the child after the fork. If whoever good citizen calling 3307after the fork. If whoever good citizen calling C<ev_default_fork> cheats
3259C<ev_default_fork> cheats and calls it in the wrong process, the fork 3308and calls it in the wrong process, the fork handlers will be invoked, too,
3260handlers will be invoked, too, of course. 3309of course.
3261 3310
3262=head3 The special problem of life after fork - how is it possible? 3311=head3 The special problem of life after fork - how is it possible?
3263 3312
3264Most uses of C<fork()> consist of forking, then some simple calls to set 3313Most uses of C<fork ()> consist of forking, then some simple calls to set
3265up/change the process environment, followed by a call to C<exec()>. This 3314up/change the process environment, followed by a call to C<exec()>. This
3266sequence should be handled by libev without any problems. 3315sequence should be handled by libev without any problems.
3267 3316
3268This changes when the application actually wants to do event handling 3317This changes when the application actually wants to do event handling
3269in the child, or both parent in child, in effect "continuing" after the 3318in the child, or both parent in child, in effect "continuing" after the
3507 3556
3508There are some other functions of possible interest. Described. Here. Now. 3557There are some other functions of possible interest. Described. Here. Now.
3509 3558
3510=over 4 3559=over 4
3511 3560
3512=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback) 3561=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback, arg)
3513 3562
3514This function combines a simple timer and an I/O watcher, calls your 3563This function combines a simple timer and an I/O watcher, calls your
3515callback on whichever event happens first and automatically stops both 3564callback on whichever event happens first and automatically stops both
3516watchers. This is useful if you want to wait for a single event on an fd 3565watchers. This is useful if you want to wait for a single event on an fd
3517or timeout without having to allocate/configure/start/stop/free one or 3566or timeout without having to allocate/configure/start/stop/free one or
3659already been invoked. 3708already been invoked.
3660 3709
3661A common way around all these issues is to make sure that 3710A common way around all these issues is to make sure that
3662C<start_new_request> I<always> returns before the callback is invoked. If 3711C<start_new_request> I<always> returns before the callback is invoked. If
3663C<start_new_request> immediately knows the result, it can artificially 3712C<start_new_request> immediately knows the result, it can artificially
3664delay invoking the callback by e.g. using a C<prepare> or C<idle> watcher 3713delay invoking the callback by using a C<prepare> or C<idle> watcher for
3665for example, or more sneakily, by reusing an existing (stopped) watcher 3714example, or more sneakily, by reusing an existing (stopped) watcher and
3666and pushing it into the pending queue: 3715pushing it into the pending queue:
3667 3716
3668 ev_set_cb (watcher, callback); 3717 ev_set_cb (watcher, callback);
3669 ev_feed_event (EV_A_ watcher, 0); 3718 ev_feed_event (EV_A_ watcher, 0);
3670 3719
3671This way, C<start_new_request> can safely return before the callback is 3720This way, C<start_new_request> can safely return before the callback is
3679 3728
3680This brings the problem of exiting - a callback might want to finish the 3729This brings the problem of exiting - a callback might want to finish the
3681main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but 3730main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
3682a modal "Are you sure?" dialog is still waiting), or just the nested one 3731a modal "Are you sure?" dialog is still waiting), or just the nested one
3683and not the main one (e.g. user clocked "Ok" in a modal dialog), or some 3732and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
3684other combination: In these cases, C<ev_break> will not work alone. 3733other combination: In these cases, a simple C<ev_break> will not work.
3685 3734
3686The solution is to maintain "break this loop" variable for each C<ev_run> 3735The solution is to maintain "break this loop" variable for each C<ev_run>
3687invocation, and use a loop around C<ev_run> until the condition is 3736invocation, and use a loop around C<ev_run> until the condition is
3688triggered, using C<EVRUN_ONCE>: 3737triggered, using C<EVRUN_ONCE>:
3689 3738
3893To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two 3942To 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: 3943files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
3895 3944
3896 // my_ev.h 3945 // my_ev.h
3897 #define EV_CB_DECLARE(type) struct my_coro *cb; 3946 #define EV_CB_DECLARE(type) struct my_coro *cb;
3898 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb); 3947 #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb)
3899 #include "../libev/ev.h" 3948 #include "../libev/ev.h"
3900 3949
3901 // my_ev.c 3950 // my_ev.c
3902 #define EV_H "my_ev.h" 3951 #define EV_H "my_ev.h"
3903 #include "../libev/ev.c" 3952 #include "../libev/ev.c"
3949The normal C API should work fine when used from C++: both ev.h and the 3998The normal C API should work fine when used from C++: both ev.h and the
3950libev sources can be compiled as C++. Therefore, code that uses the C API 3999libev sources can be compiled as C++. Therefore, code that uses the C API
3951will work fine. 4000will work fine.
3952 4001
3953Proper exception specifications might have to be added to callbacks passed 4002Proper exception specifications might have to be added to callbacks passed
3954to libev: exceptions may be thrown only from watcher callbacks, all 4003to libev: exceptions may be thrown only from watcher callbacks, all other
3955other callbacks (allocator, syserr, loop acquire/release and periodioc 4004callbacks (allocator, syserr, loop acquire/release and periodic reschedule
3956reschedule callbacks) must not throw exceptions, and might need a C<throw 4005callbacks) must not throw exceptions, and might need a C<noexcept>
3957()> specification. If you have code that needs to be compiled as both C 4006specification. If you have code that needs to be compiled as both C and
3958and C++ you can use the C<EV_THROW> macro for this: 4007C++ you can use the C<EV_NOEXCEPT> macro for this:
3959 4008
3960 static void 4009 static void
3961 fatal_error (const char *msg) EV_THROW 4010 fatal_error (const char *msg) EV_NOEXCEPT
3962 { 4011 {
3963 perror (msg); 4012 perror (msg);
3964 abort (); 4013 abort ();
3965 } 4014 }
3966 4015
3980Libev comes with some simplistic wrapper classes for C++ that mainly allow 4029Libev comes with some simplistic wrapper classes for C++ that mainly allow
3981you to use some convenience methods to start/stop watchers and also change 4030you to use some convenience methods to start/stop watchers and also change
3982the callback model to a model using method callbacks on objects. 4031the callback model to a model using method callbacks on objects.
3983 4032
3984To use it, 4033To use it,
3985 4034
3986 #include <ev++.h> 4035 #include <ev++.h>
3987 4036
3988This automatically includes F<ev.h> and puts all of its definitions (many 4037This automatically includes F<ev.h> and puts all of its definitions (many
3989of them macros) into the global namespace. All C++ specific things are 4038of them macros) into the global namespace. All C++ specific things are
3990put into the C<ev> namespace. It should support all the same embedding 4039put into the C<ev> namespace. It should support all the same embedding
4093 void operator() (ev::io &w, int revents) 4142 void operator() (ev::io &w, int revents)
4094 { 4143 {
4095 ... 4144 ...
4096 } 4145 }
4097 } 4146 }
4098 4147
4099 myfunctor f; 4148 myfunctor f;
4100 4149
4101 ev::io w; 4150 ev::io w;
4102 w.set (&f); 4151 w.set (&f);
4103 4152
4121Associates a different C<struct ev_loop> with this watcher. You can only 4170Associates a different C<struct ev_loop> with this watcher. You can only
4122do this when the watcher is inactive (and not pending either). 4171do this when the watcher is inactive (and not pending either).
4123 4172
4124=item w->set ([arguments]) 4173=item w->set ([arguments])
4125 4174
4126Basically the same as C<ev_TYPE_set>, with the same arguments. Either this 4175Basically the same as C<ev_TYPE_set> (except for C<ev::embed> watchers>),
4127method or a suitable start method must be called at least once. Unlike the 4176with the same arguments. Either this method or a suitable start method
4128C counterpart, an active watcher gets automatically stopped and restarted 4177must be called at least once. Unlike the C counterpart, an active watcher
4129when reconfiguring it with this method. 4178gets automatically stopped and restarted when reconfiguring it with this
4179method.
4180
4181For C<ev::embed> watchers this method is called C<set_embed>, to avoid
4182clashing with the C<set (loop)> method.
4130 4183
4131=item w->start () 4184=item w->start ()
4132 4185
4133Starts the watcher. Note that there is no C<loop> argument, as the 4186Starts the watcher. Note that there is no C<loop> argument, as the
4134constructor already stores the event loop. 4187constructor already stores the event loop.
4372 ev_vars.h 4425 ev_vars.h
4373 ev_wrap.h 4426 ev_wrap.h
4374 4427
4375 ev_win32.c required on win32 platforms only 4428 ev_win32.c required on win32 platforms only
4376 4429
4377 ev_select.c only when select backend is enabled (which is enabled by default) 4430 ev_select.c only when select backend is enabled
4378 ev_poll.c only when poll backend is enabled (disabled by default) 4431 ev_poll.c only when poll backend is enabled
4379 ev_epoll.c only when the epoll backend is enabled (disabled by default) 4432 ev_epoll.c only when the epoll backend is enabled
4380 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 4433 ev_kqueue.c only when the kqueue backend is enabled
4381 ev_port.c only when the solaris port backend is enabled (disabled by default) 4434 ev_port.c only when the solaris port backend is enabled
4382 4435
4383F<ev.c> includes the backend files directly when enabled, so you only need 4436F<ev.c> includes the backend files directly when enabled, so you only need
4384to compile this single file. 4437to compile this single file.
4385 4438
4386=head3 LIBEVENT COMPATIBILITY API 4439=head3 LIBEVENT COMPATIBILITY API
4553 4606
4554If programs implement their own fd to handle mapping on win32, then this 4607If programs implement their own fd to handle mapping on win32, then this
4555macro can be used to override the C<close> function, useful to unregister 4608macro can be used to override the C<close> function, useful to unregister
4556file descriptors again. Note that the replacement function has to close 4609file descriptors again. Note that the replacement function has to close
4557the underlying OS handle. 4610the underlying OS handle.
4611
4612=item EV_USE_WSASOCKET
4613
4614If defined to be C<1>, libev will use C<WSASocket> to create its internal
4615communication socket, which works better in some environments. Otherwise,
4616the normal C<socket> function will be used, which works better in other
4617environments.
4558 4618
4559=item EV_USE_POLL 4619=item EV_USE_POLL
4560 4620
4561If defined to be C<1>, libev will compile in support for the C<poll>(2) 4621If defined to be C<1>, libev will compile in support for the C<poll>(2)
4562backend. Otherwise it will be enabled on non-win32 platforms. It 4622backend. Otherwise it will be enabled on non-win32 platforms. It
4607different cpus (or different cpu cores). This reduces dependencies 4667different cpus (or different cpu cores). This reduces dependencies
4608and makes libev faster. 4668and makes libev faster.
4609 4669
4610=item EV_NO_THREADS 4670=item EV_NO_THREADS
4611 4671
4612If defined to be C<1>, libev will assume that it will never be called 4672If defined to be C<1>, libev will assume that it will never be called from
4613from different threads, which is a stronger assumption than C<EV_NO_SMP>, 4673different threads (that includes signal handlers), which is a stronger
4614above. This reduces dependencies and makes libev faster. 4674assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
4675libev faster.
4615 4676
4616=item EV_ATOMIC_T 4677=item EV_ATOMIC_T
4617 4678
4618Libev requires an integer type (suitable for storing C<0> or C<1>) whose 4679Libev requires an integer type (suitable for storing C<0> or C<1>) whose
4619access is atomic and serialised with respect to other threads or signal 4680access is atomic with respect to other threads or signal contexts. No
4620contexts. No such type is easily found in the C language, so you can 4681such type is easily found in the C language, so you can provide your own
4621provide your own type that you know is safe for your purposes. It is used 4682type that you know is safe for your purposes. It is used both for signal
4622both for signal handler "locking" as well as for signal and thread safety 4683handler "locking" as well as for signal and thread safety in C<ev_async>
4623in C<ev_async> watchers. 4684watchers.
4624 4685
4625In the absence of this define, libev will use C<sig_atomic_t volatile> 4686In the absence of this define, libev will use C<sig_atomic_t volatile>
4626(from F<signal.h>), which is usually good enough on most platforms, 4687(from F<signal.h>), which is usually good enough on most platforms.
4627although strictly speaking using a type that also implies a memory fence
4628is required.
4629 4688
4630=item EV_H (h) 4689=item EV_H (h)
4631 4690
4632The name of the F<ev.h> header file used to include it. The default if 4691The name of the F<ev.h> header file used to include it. The default if
4633undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 4692undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
5280structure (guaranteed by POSIX but not by ISO C for example), but it also 5339structure (guaranteed by POSIX but not by ISO C for example), but it also
5281assumes that the same (machine) code can be used to call any watcher 5340assumes that the same (machine) code can be used to call any watcher
5282callback: The watcher callbacks have different type signatures, but libev 5341callback: The watcher callbacks have different type signatures, but libev
5283calls them using an C<ev_watcher *> internally. 5342calls them using an C<ev_watcher *> internally.
5284 5343
5344=item null pointers and integer zero are represented by 0 bytes
5345
5346Libev uses C<memset> to initialise structs and arrays to C<0> bytes, and
5347relies on this setting pointers and integers to null.
5348
5285=item pointer accesses must be thread-atomic 5349=item pointer accesses must be thread-atomic
5286 5350
5287Accessing a pointer value must be atomic, it must both be readable and 5351Accessing a pointer value must be atomic, it must both be readable and
5288writable in one piece - this is the case on all current architectures. 5352writable in one piece - this is the case on all current architectures.
5289 5353
5302thread" or will block signals process-wide, both behaviours would 5366thread" or will block signals process-wide, both behaviours would
5303be compatible with libev. Interaction between C<sigprocmask> and 5367be compatible with libev. Interaction between C<sigprocmask> and
5304C<pthread_sigmask> could complicate things, however. 5368C<pthread_sigmask> could complicate things, however.
5305 5369
5306The most portable way to handle signals is to block signals in all threads 5370The most portable way to handle signals is to block signals in all threads
5307except the initial one, and run the default loop in the initial thread as 5371except the initial one, and run the signal handling loop in the initial
5308well. 5372thread as well.
5309 5373
5310=item C<long> must be large enough for common memory allocation sizes 5374=item C<long> must be large enough for common memory allocation sizes
5311 5375
5312To improve portability and simplify its API, libev uses C<long> internally 5376To improve portability and simplify its API, libev uses C<long> internally
5313instead of C<size_t> when allocating its data structures. On non-POSIX 5377instead of C<size_t> when allocating its data structures. On non-POSIX
5417=over 4 5481=over 4
5418 5482
5419=item C<EV_COMPAT3> backwards compatibility mechanism 5483=item C<EV_COMPAT3> backwards compatibility mechanism
5420 5484
5421The backward compatibility mechanism can be controlled by 5485The backward compatibility mechanism can be controlled by
5422C<EV_COMPAT3>. See L</PREPROCESSOR SYMBOLS/MACROS> in the L</EMBEDDING> 5486C<EV_COMPAT3>. See L</"PREPROCESSOR SYMBOLS/MACROS"> in the L</EMBEDDING>
5423section. 5487section.
5424 5488
5425=item C<ev_default_destroy> and C<ev_default_fork> have been removed 5489=item C<ev_default_destroy> and C<ev_default_fork> have been removed
5426 5490
5427These calls can be replaced easily by their C<ev_loop_xxx> counterparts: 5491These calls can be replaced easily by their C<ev_loop_xxx> counterparts:

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines