ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.304 by root, Fri Dec 11 18:09:24 2009 UTC vs.
Revision 1.309 by root, Sat Dec 26 08:59:35 2009 UTC

… …
503 503
504=head2 IDLE WATCHERS 504=head2 IDLE WATCHERS
505 505
506 $w = AnyEvent->idle (cb => <callback>); 506 $w = AnyEvent->idle (cb => <callback>);
507 507
508Sometimes there is a need to do something, but it is not so important 508Repeatedly invoke the callback after the process becomes idle, until
509to do it instantly, but only when there is nothing better to do. This 509either the watcher is destroyed or new events have been detected.
510"nothing better to do" is usually defined to be "no other events need
511attention by the event loop".
512 510
513Idle watchers ideally get invoked when the event loop has nothing 511Idle watchers are useful when there is a need to do something, but it
514better to do, just before it would block the process to wait for new 512is not so important (or wise) to do it instantly. The callback will be
515events. Instead of blocking, the idle watcher is invoked. 513invoked only when there is "nothing better to do", which is usually
514defined as "all outstanding events have been handled and no new events
515have been detected". That means that idle watchers ideally get invoked
516when the event loop has just polled for new events but none have been
517detected. Instead of blocking to wait for more events, the idle watchers
518will be invoked.
516 519
517Most event loops unfortunately do not really support idle watchers (only 520Unfortunately, most event loops do not really support idle watchers (only
518EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent 521EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
519will simply call the callback "from time to time". 522will simply call the callback "from time to time".
520 523
521Example: read lines from STDIN, but only process them when the 524Example: read lines from STDIN, but only process them when the
522program is otherwise idle: 525program is otherwise idle:
… …
1144package AnyEvent; 1147package AnyEvent;
1145 1148
1146# basically a tuned-down version of common::sense 1149# basically a tuned-down version of common::sense
1147sub common_sense { 1150sub common_sense {
1148 # from common:.sense 1.0 1151 # from common:.sense 1.0
1149 ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x03"; 1152 ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00";
1150 # use strict vars subs 1153 # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl)
1151 $^H |= 0x00000600; 1154 $^H |= 0x00000600;
1152} 1155}
1153 1156
1154BEGIN { AnyEvent::common_sense } 1157BEGIN { AnyEvent::common_sense }
1155 1158
1156use Carp (); 1159use Carp ();
1157 1160
1158our $VERSION = '5.22'; 1161our $VERSION = '5.23';
1159our $MODEL; 1162our $MODEL;
1160 1163
1161our $AUTOLOAD; 1164our $AUTOLOAD;
1162our @ISA; 1165our @ISA;
1163 1166
… …
2534 2537
2535 2538
2536=head1 FORK 2539=head1 FORK
2537 2540
2538Most event libraries are not fork-safe. The ones who are usually are 2541Most event libraries are not fork-safe. The ones who are usually are
2539because they rely on inefficient but fork-safe C<select> or C<poll> 2542because they rely on inefficient but fork-safe C<select> or C<poll> calls
2540calls. Only L<EV> is fully fork-aware. 2543- higher performance APIs such as BSD's kqueue or the dreaded Linux epoll
2544are usually badly thought-out hacks that are incompatible with fork in
2545one way or another. Only L<EV> is fully fork-aware and ensures that you
2546continue event-processing in both parent and child (or both, if you know
2547what you are doing).
2541 2548
2542This means that, in general, you cannot fork and do event processing 2549This means that, in general, you cannot fork and do event processing in
2543in the child if a watcher was created before the fork (which in turn 2550the child if the event library was initialised before the fork (which
2544initialises the event library). 2551usually happens when the first AnyEvent watcher is created, or the library
2552is loaded).
2545 2553
2546If you have to fork, you must either do so I<before> creating your first 2554If you have to fork, you must either do so I<before> creating your first
2547watcher OR you must not use AnyEvent at all in the child OR you must do 2555watcher OR you must not use AnyEvent at all in the child OR you must do
2548something completely out of the scope of AnyEvent. 2556something completely out of the scope of AnyEvent.
2549 2557
2550The problem of doing event processing in the parent I<and> the child 2558The problem of doing event processing in the parent I<and> the child
2551is much more complicated: even for backends that I<are> fork-aware or 2559is much more complicated: even for backends that I<are> fork-aware or
2552fork-safe, their behaviour is not usually what you want: fork clones all 2560fork-safe, their behaviour is not usually what you want: fork clones all
2553watchers, that means all timers, I/O watchers etc. are active in both 2561watchers, that means all timers, I/O watchers etc. are active in both
2554parent and child, which is almost never what you want. 2562parent and child, which is almost never what you want. USing C<exec>
2563to start worker children from some kind of manage rprocess is usually
2564preferred, because it is much easier and cleaner, at the expense of having
2565to have another binary.
2555 2566
2556 2567
2557=head1 SECURITY CONSIDERATIONS 2568=head1 SECURITY CONSIDERATIONS
2558 2569
2559AnyEvent can be forced to load any event model via 2570AnyEvent can be forced to load any event model via

Diff Legend

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