--- libev/ev.pod 2012/05/03 15:07:15 1.405 +++ libev/ev.pod 2012/05/03 16:00:47 1.406 @@ -2849,6 +2849,20 @@ "pseudo-background processing", or delay processing stuff to after the event loop has handled all outstanding events. +=head3 Abusing an C watcher for its side-effect + +As long as there is at least one active idle watcher, libev will never +sleep unnecessarily. Or in other words, it will loop as fast as possible. +For this to work, the idle watcher doesn't need to be invoked at all - the +lowest priority will do. + +This mode of operation can be useful together with an C watcher, +to do something on each event loop iteration - for example to balance load +between different connections. + +See L watcher for its side-effect> for a longer +example. + =head3 Watcher-Specific Functions and Data Members =over 4 @@ -2881,7 +2895,7 @@ =head2 C and C - customise your event loop! -Prepare and check watchers are usually (but not always) used in pairs: +Prepare and check watchers are often (but not always) used in pairs: prepare watchers get invoked before the process blocks and check watchers afterwards. @@ -2919,9 +2933,10 @@ loop from blocking if lower-priority coroutines are active, thus mapping low-priority coroutines to idle/background tasks). -It is recommended to give C watchers highest (C) -priority, to ensure that they are being run before any other watchers -after the poll (this doesn't matter for C watchers). +When used for this purpose, it is recommended to give C watchers +highest (C) priority, to ensure that they are being run before +any other watchers after the poll (this doesn't matter for C +watchers). Also, C watchers (and C watchers, too) should not activate ("feed") events into libev. While libev fully supports this, they @@ -2931,6 +2946,26 @@ C watcher ran (always remind yourself to coexist peacefully with others). +=head3 Abusing an C watcher for its side-effect + +C (and less often also C) watchers can also be +useful because they are called once per event loop iteration. For +example, if you want to handle a large number of connections fairly, you +normally only do a bit of work for each active connection, and if there +is more work to do, you wait for the next event loop iteration, so other +connections have a chance of making progress. + +Using an C watcher is almost enough: it will be called on the +next event loop iteration. However, that isn't as soon as possible - +without external events, your C watcher will not be invoked. + + +This is where C watchers come in handy - all you need is a +single global idle watcher that is active as long as you have one active +C watcher. The C watcher makes sure the event loop +will not sleep, and the C watcher makes sure a callback gets +invoked. Neither watcher alone can do that. + =head3 Watcher-Specific Functions and Data Members =over 4