EV/EV.pm

=head1 NAME

EV - perl interface to libev, a high performance full-featured event loop

=head1 SYNOPSIS

  use EV;
  
  # TIMERS
  
  my $w = EV::timer 2, 0, sub {
     warn "is called after 2s";
  };
  
  my $w = EV::timer 2, 1, sub {
     warn "is called roughly every 2s (repeat = 1)";
  };
  
  undef $w; # destroy event watcher again
  
  my $w = EV::periodic 0, 60, sub {
     warn "is called every minute, on the minute, exactly";
  };
  
  # IO
  
  my $w = EV::io *STDIN, EV::READ, sub {
     my ($w, $revents) = @_; # all callbacks get the watcher object and event mask
     warn "stdin is readable, you entered: ", <STDIN>;
  };
  
  # SIGNALS
  
  my $w = EV::signal 'QUIT', sub {
     warn "sigquit received\n";
  };
  
  my $w = EV::signal 3, sub {
     warn "sigquit received (this is GNU/Linux, right?)\n";
  };

  # CHILD/PID STATUS CHANGES

  my $w = EV::child 666, sub {
     my ($w, $revents, $status) = @_;
  };
  
  # MAINLOOP
  EV::loop;                   # loop until EV::loop_done is called
  EV::loop EV::LOOP_ONESHOT;  # block until at least one event could be handled
  EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block

=head1 DESCRIPTION

This module provides an interface to libev
(L<http://software.schmorp.de/pkg/libev.html>).

=cut

package EV;

use strict;

BEGIN {
   our $VERSION = '0.1';
   use XSLoader;
   XSLoader::load "EV", $VERSION;
}

@EV::Io::ISA       =
@EV::Timer::ISA    =
@EV::Periodic::ISA =
@EV::Signal::ISA   =
@EV::Idle::ISA     =
@EV::Prepare::ISA  =
@EV::Check::ISA    =
@EV::Child::ISA    = "EV::Watcher";

=head1 BASIC INTERFACE

=over 4

=item $EV::DIED

Must contain a reference to a function that is called when a callback
throws an exception (with $@ containing thr error). The default prints an
informative message and continues.

If this callback throws an exception it will be silently ignored.

=item $time = EV::time

Returns the current time in (fractional) seconds since the epoch.

=item $time = EV::now

Returns the time the last event loop iteration has been started. This
is the time that (relative) timers are based on, and refering to it is
usually faster then calling EV::time.

=item $method = EV::ev_method

Returns an integer describing the backend used by libev (EV::METHOD_SELECT
or EV::METHOD_EPOLL).

=item EV::loop [$flags]

Begin checking for events and calling callbacks. It returns when a
callback calls EV::loop_done.

The $flags argument can be one of the following:

   0                  as above
   EV::LOOP_ONESHOT   block at most once (wait, but do not loop)
   EV::LOOP_NONBLOCK  do not block at all (fetch/handle events but do not wait)

=item EV::loop_done [$how]

When called with no arguments or an argument of 1, makes the innermost
call to EV::loop return.

When called with an agrument of 2, all calls to EV::loop will return as
fast as possible.

=back

=head2 WATCHER

A watcher is an object that gets created to record your interest in some
event. For instance, if you want to wait for STDIN to become readable, you
would create an EV::io watcher for that:

  my $watcher = EV::io *STDIN, EV::READ, sub {
     my ($watcher, $revents) = @_;
     warn "yeah, STDIN should not be readable without blocking!\n"
  };

All watchers can be active (waiting for events) or inactive (paused). Only
active watchers will have their callbacks invoked. All callbacks will be
called with at least two arguments: the watcher and a bitmask of received
events.

Each watcher type has its associated bit in revents, so you can use the
same callback for multiple watchers. The event mask is named after the
type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
EV::periodic sets EV::PERIODIC and so on, with the exception of IO events
(which can set both EV::READ and EV::WRITE bits), and EV::timer (which
uses EV::TIMEOUT).

In the rare case where one wants to create a watcher but not start it at
the same time, each constructor has a variant with a trailing C<_ns> in
its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.

Please note that a watcher will automatically be stopped when the watcher
object is returned, so you I<need> to keep the watcher objects returned by
the constructors.

=head2 WATCHER TYPES

Now lets move to the existing watcher types and asociated methods.

The following methods are available for all watchers. Then followes a
description of each watcher constructor (EV::io, EV::timer, EV::periodic,
EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
any type-specific methods (if any).

=over 4

=item $w->start

Starts a watcher if it isn't active already. Does nothing to an already
active watcher. By default, all watchers start out in the active state
(see the description of the C<_ns> variants if you need stopped watchers).

=item $w->stop

Stop a watcher if it is active. Also clear any pending events (events that
have been received but that didn't yet result in a callback invocation),
regardless of wether the watcher was active or not.

=item $bool = $w->is_active

Returns true if the watcher is active, false otherwise.

=item $current_cb = $w->cb

=item $old_cb = $w->cb ($new_cb)

Queries the callback on the watcher and optionally changes it. You cna do
this at any time.

=item $w->trigger ($revents)

Call the callback *now* with the given event mask.


=item $w = EV::io $fileno_or_fh, $eventmask, $callback

=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback

As long as the returned watcher object is alive, call the C<$callback>
when the events specified in C<$eventmask>.

The $eventmask can be one or more of these constants ORed together:

  EV::READ     wait until read() wouldn't block anymore
  EV::WRITE    wait until write() wouldn't block anymore

The C<io_ns> variant doesn't start (activate) the newly created watcher.

=item $w->set ($fileno_or_fh, $eventmask)

Reconfigures the watcher, see the constructor above for details. Can be
called at any time.

=item $current_fh = $w->fh

=item $old_fh = $w->fh ($new_fh)

Returns the previously set filehandle and optionally set a new one.

=item $current_eventmask = $w->events

=item $old_eventmask = $w->events ($new_eventmask)

Returns the previously set event mask and optionally set a new one.


=item $w = EV::timer $after, $repeat, $callback

=item $w = EV::timer_ns $after, $repeat, $callback

Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
the timer will be restarted (with the $repeat value as $after) after the
callback returns.

This means that the callback would be called roughly after C<$after>
seconds, and then every C<$repeat> seconds. "Roughly" because the time of
callback processing is not taken into account, so the timer will slowly
drift. If that isn't acceptable, look at EV::periodic.

The timer is based on a monotonic clock, that is if somebody is sitting
in front of the machine while the timer is running and changes the system
clock, the timer will nevertheless run (roughly) the same time.

The C<timer_ns> variant doesn't start (activate) the newly created watcher.

=item $w->set ($after, $repeat)

Reconfigures the watcher, see the constructor above for details. Can be at
any time.

=item $w->again

Similar to the C<start> method, but has special semantics for repeating timers:

If the timer is active and repeating, reset the timeout to occur
C<$repeat> seconds after now.

If the timer is active and non-repeating, it will be stopped.

If the timer is in active and repeating, start it.

Otherwise do nothing.

This behaviour is useful when you have a timeout for some IO
operation. You create a timer object with the same value for C<$after> and
C<$repeat>, and then, in the read/write watcher, run the C<again> method
on the timeout.


=item $w = EV::periodic $at, $interval, $callback

=item $w = EV::periodic_ns $at, $interval, $callback

Similar to EV::timer, but the time is given as an absolute point in time
(C<$at>), plus an optional C<$interval>.

If the C<$interval> is zero, then the callback will be called at the time
C<$at> if that is in the future, or as soon as possible if it is in the
past. It will not automatically repeat.

If the C<$interval> is nonzero, then the watcher will always be scheduled
to time out at the next C<$at + N * $interval> time.

This can be used to schedule a callback to run at very regular intervals,
as long as the processing time is less then the interval (otherwise
obviously events will be skipped).

Another way to think about it (for the mathematically inclined) is that
EV::periodic will try to run the callback at the next possible time where
C<$time = $at (mod $interval)>, regardless of any time jumps.

This periodic timer is based on "wallclock time", that is, if the clock
changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at
the specified time. This means it will never drift (it might jitter, but
it will not drift).

The C<periodic_ns> variant doesn't start (activate) the newly created watcher.

=item $w->set ($at, $interval)

Reconfigures the watcher, see the constructor above for details. Can be at
any time.


=item $w = EV::signal $signal, $callback

=item $w = EV::signal_ns $signal, $callback

Call the callback when $signal is received (the signal can be specified
by number or by name, just as with kill or %SIG).

EV will grab the signal for the process (the kernel only allows one
component to receive a signal at a time) when you start a signal watcher,
and removes it again when you stop it. Perl does the same when you
add/remove callbacks to %SIG, so watch out.

You can have as many signal watchers per signal as you want.

The C<signal_ns> variant doesn't start (activate) the newly created watcher.

=item $w->set ($signal)

Reconfigures the watcher, see the constructor above for details. Can be at
any time.


=item $w = EV::child $pid, $callback

=item $w = EV::child_ns $pid, $callback

Call the callback when a status change for pid C<$pid> (or any pid
if C<$pid> is 0) has been received. More precisely: when the process
receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
changed/zombie children and call the callback.

Unlike all other callbacks, this callback will be called with an
additional third argument which is the exit status. See the C<waitpid>
function for details.

You can have as many pid watchers per pid as you want.

The C<child_ns> variant doesn't start (activate) the newly created watcher.

=item $w->set ($pid)

Reconfigures the watcher, see the constructor above for details. Can be at
any time.


=item $w = EV::idle $callback

=item $w = EV::idle_ns $callback

Call the callback when there are no pending io, timer/periodic, signal or
child events, i.e. when the process is idle.

The process will not block as long as any idle watchers are active, and
they will be called repeatedly until stopped.

The C<idle_ns> variant doesn't start (activate) the newly created watcher.


=item $w = EV::prepare $callback

=item $w = EV::prepare_ns $callback

Call the callback just before the process would block. You can still
create/modify any watchers at this point.

See the EV::check watcher, below, for explanations and an example.

The C<prepare_ns> variant doesn't start (activate) the newly created watcher.


=item $w = EV::check $callback

=item $w = EV::check_ns $callback

Call the callback just after the process wakes up again (after it has
gathered events), but before any other callbacks have been invoked.

This is used to integrate other event-based software into the EV
mainloop: You register a prepare callback and in there, you create io and
timer watchers as required by the other software. Here is a real-world
example of integrating Net::SNMP (with some details left out):

   our @snmp_watcher;

   our $snmp_prepare = EV::prepare sub {
      # do nothing unless active
      $dispatcher->{_event_queue_h}
         or return;

      # make the dispatcher handle any outstanding stuff

      # create an IO watcher for each and every socket
      @snmp_watcher = (
         (map { EV::io $_, EV::READ, sub { } }
             keys %{ $dispatcher->{_descriptors} }),
      );

      # if there are any timeouts, also create a timer
      push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
         if $event->[Net::SNMP::Dispatcher::_ACTIVE];
   };

The callbacks are irrelevant, the only purpose of those watchers is
to wake up the process as soon as one of those events occurs (socket
readable, or timer timed out). The corresponding EV::check watcher will then
clean up:

   our $snmp_check = EV::check sub {
      # destroy all watchers
      @snmp_watcher = ();

      # make the dispatcher handle any new stuff
   };

The callbacks of the created watchers will not be called as the watchers
are destroyed before this cna happen (remember EV::check gets called
first).

The C<check_ns> variant doesn't start (activate) the newly created watcher.

=back

=head1 THREADS

Threads are not supported by this in any way. Perl pseudo-threads is evil
stuff and must die.

=cut

our $DIED = sub {
   warn "EV: error in callback (ignoring): $@";
};

init;

push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];

1;

=head1 SEE ALSO

  L<EV::DNS>, L<EV::AnyEvent>.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.21
Committed:	Thu Nov 1 17:20:25 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.20:	+2 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.20	EV - perl interface to libev, a high performance full-featured event loop
4	root	1.1
5			=head1 SYNOPSIS
6
7	root	1.11	use EV;
8
9	root	1.20	# TIMERS
10	root	1.11
11			my $w = EV::timer 2, 0, sub {
12			warn "is called after 2s";
13			};
14
15			my $w = EV::timer 2, 1, sub {
16			warn "is called roughly every 2s (repeat = 1)";
17			};
18
19			undef $w; # destroy event watcher again
20
21	root	1.20	my $w = EV::periodic 0, 60, sub {
22	root	1.11	warn "is called every minute, on the minute, exactly";
23			};
24
25			# IO
26
27	root	1.20	my $w = EV::io *STDIN, EV::READ, sub {
28	root	1.16	my ($w, $revents) = @_; # all callbacks get the watcher object and event mask
29	root	1.20	warn "stdin is readable, you entered: ", <STDIN>;
30	root	1.11	};
31
32			# SIGNALS
33
34			my $w = EV::signal 'QUIT', sub {
35			warn "sigquit received\n";
36			};
37
38			my $w = EV::signal 3, sub {
39			warn "sigquit received (this is GNU/Linux, right?)\n";
40			};
41	root	1.16
42			# CHILD/PID STATUS CHANGES
43
44			my $w = EV::child 666, sub {
45			my ($w, $revents, $status) = @_;
46			};
47	root	1.11
48			# MAINLOOP
49	root	1.20	EV::loop; # loop until EV::loop_done is called
50			EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
51			EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
52	root	1.2
53	root	1.1	=head1 DESCRIPTION
54
55	root	1.16	This module provides an interface to libev
56	root	1.20	(L<http://software.schmorp.de/pkg/libev.html>).
57	root	1.1
58			=cut
59
60			package EV;
61
62			use strict;
63
64			BEGIN {
65	root	1.19	our $VERSION = '0.1';
66	root	1.1	use XSLoader;
67			XSLoader::load "EV", $VERSION;
68			}
69
70	root	1.18	@EV::Io::ISA =
71			@EV::Timer::ISA =
72			@EV::Periodic::ISA =
73			@EV::Signal::ISA =
74			@EV::Idle::ISA =
75			@EV::Prepare::ISA =
76			@EV::Check::ISA =
77	root	1.17	@EV::Child::ISA = "EV::Watcher";
78	root	1.15
79	root	1.8	=head1 BASIC INTERFACE
80	root	1.1
81			=over 4
82
83	root	1.8	=item $EV::DIED
84
85			Must contain a reference to a function that is called when a callback
86			throws an exception (with $@ containing thr error). The default prints an
87			informative message and continues.
88
89			If this callback throws an exception it will be silently ignored.
90
91	root	1.20	=item $time = EV::time
92
93			Returns the current time in (fractional) seconds since the epoch.
94
95	root	1.2	=item $time = EV::now
96
97	root	1.20	Returns the time the last event loop iteration has been started. This
98			is the time that (relative) timers are based on, and refering to it is
99			usually faster then calling EV::time.
100
101			=item $method = EV::ev_method
102
103			Returns an integer describing the backend used by libev (EV::METHOD_SELECT
104			or EV::METHOD_EPOLL).
105
106			=item EV::loop [$flags]
107	root	1.2
108	root	1.20	Begin checking for events and calling callbacks. It returns when a
109			callback calls EV::loop_done.
110	root	1.2
111	root	1.20	The $flags argument can be one of the following:
112	root	1.2
113	root	1.20	0 as above
114			EV::LOOP_ONESHOT block at most once (wait, but do not loop)
115			EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait)
116	root	1.2
117	root	1.20	=item EV::loop_done [$how]
118	root	1.2
119	root	1.20	When called with no arguments or an argument of 1, makes the innermost
120			call to EV::loop return.
121	root	1.2
122	root	1.20	When called with an agrument of 2, all calls to EV::loop will return as
123			fast as possible.
124	root	1.2
125	root	1.20	=back
126
127			=head2 WATCHER
128	root	1.2
129	root	1.20	A watcher is an object that gets created to record your interest in some
130			event. For instance, if you want to wait for STDIN to become readable, you
131			would create an EV::io watcher for that:
132
133			my $watcher = EV::io *STDIN, EV::READ, sub {
134			my ($watcher, $revents) = @_;
135			warn "yeah, STDIN should not be readable without blocking!\n"
136			};
137	root	1.2
138	root	1.20	All watchers can be active (waiting for events) or inactive (paused). Only
139			active watchers will have their callbacks invoked. All callbacks will be
140			called with at least two arguments: the watcher and a bitmask of received
141			events.
142
143			Each watcher type has its associated bit in revents, so you can use the
144			same callback for multiple watchers. The event mask is named after the
145			type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
146			EV::periodic sets EV::PERIODIC and so on, with the exception of IO events
147			(which can set both EV::READ and EV::WRITE bits), and EV::timer (which
148			uses EV::TIMEOUT).
149
150			In the rare case where one wants to create a watcher but not start it at
151			the same time, each constructor has a variant with a trailing C<_ns> in
152			its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
153
154			Please note that a watcher will automatically be stopped when the watcher
155			object is returned, so you I<need> to keep the watcher objects returned by
156			the constructors.
157
158			=head2 WATCHER TYPES
159
160			Now lets move to the existing watcher types and asociated methods.
161
162			The following methods are available for all watchers. Then followes a
163			description of each watcher constructor (EV::io, EV::timer, EV::periodic,
164			EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
165			any type-specific methods (if any).
166
167			=over 4
168	root	1.2
169	root	1.20	=item $w->start
170
171			Starts a watcher if it isn't active already. Does nothing to an already
172			active watcher. By default, all watchers start out in the active state
173			(see the description of the C<_ns> variants if you need stopped watchers).
174
175			=item $w->stop
176	root	1.2
177	root	1.20	Stop a watcher if it is active. Also clear any pending events (events that
178			have been received but that didn't yet result in a callback invocation),
179			regardless of wether the watcher was active or not.
180	root	1.2
181	root	1.20	=item $bool = $w->is_active
182	root	1.2
183	root	1.20	Returns true if the watcher is active, false otherwise.
184
185			=item $current_cb = $w->cb
186
187			=item $old_cb = $w->cb ($new_cb)
188
189			Queries the callback on the watcher and optionally changes it. You cna do
190			this at any time.
191
192			=item $w->trigger ($revents)
193
194			Call the callback now with the given event mask.
195
196
197			=item $w = EV::io $fileno_or_fh, $eventmask, $callback
198	root	1.2
199	root	1.20	=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
200	root	1.7
201	root	1.20	As long as the returned watcher object is alive, call the C<$callback>
202			when the events specified in C<$eventmask>.
203	root	1.2
204	root	1.20	The $eventmask can be one or more of these constants ORed together:
205	root	1.2
206			EV::READ wait until read() wouldn't block anymore
207			EV::WRITE wait until write() wouldn't block anymore
208	root	1.7
209	root	1.20	The C<io_ns> variant doesn't start (activate) the newly created watcher.
210	root	1.2
211	root	1.20	=item $w->set ($fileno_or_fh, $eventmask)
212	root	1.10
213	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be
214			called at any time.
215	root	1.10
216	root	1.20	=item $current_fh = $w->fh
217
218			=item $old_fh = $w->fh ($new_fh)
219
220			Returns the previously set filehandle and optionally set a new one.
221	root	1.10
222	root	1.20	=item $current_eventmask = $w->events
223
224			=item $old_eventmask = $w->events ($new_eventmask)
225	root	1.10
226	root	1.20	Returns the previously set event mask and optionally set a new one.
227	root	1.10
228
229	root	1.20	=item $w = EV::timer $after, $repeat, $callback
230	root	1.2
231	root	1.20	=item $w = EV::timer_ns $after, $repeat, $callback
232	root	1.2
233	root	1.20	Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
234			the timer will be restarted (with the $repeat value as $after) after the
235			callback returns.
236	root	1.2
237	root	1.20	This means that the callback would be called roughly after C<$after>
238			seconds, and then every C<$repeat> seconds. "Roughly" because the time of
239			callback processing is not taken into account, so the timer will slowly
240			drift. If that isn't acceptable, look at EV::periodic.
241	root	1.2
242	root	1.20	The timer is based on a monotonic clock, that is if somebody is sitting
243			in front of the machine while the timer is running and changes the system
244			clock, the timer will nevertheless run (roughly) the same time.
245	root	1.2
246	root	1.20	The C<timer_ns> variant doesn't start (activate) the newly created watcher.
247
248			=item $w->set ($after, $repeat)
249
250			Reconfigures the watcher, see the constructor above for details. Can be at
251			any time.
252
253			=item $w->again
254
255			Similar to the C<start> method, but has special semantics for repeating timers:
256
257			If the timer is active and repeating, reset the timeout to occur
258			C<$repeat> seconds after now.
259
260			If the timer is active and non-repeating, it will be stopped.
261
262			If the timer is in active and repeating, start it.
263
264			Otherwise do nothing.
265
266			This behaviour is useful when you have a timeout for some IO
267			operation. You create a timer object with the same value for C<$after> and
268			C<$repeat>, and then, in the read/write watcher, run the C<again> method
269			on the timeout.
270
271
272			=item $w = EV::periodic $at, $interval, $callback
273
274			=item $w = EV::periodic_ns $at, $interval, $callback
275	root	1.2
276			Similar to EV::timer, but the time is given as an absolute point in time
277			(C<$at>), plus an optional C<$interval>.
278
279			If the C<$interval> is zero, then the callback will be called at the time
280	root	1.20	C<$at> if that is in the future, or as soon as possible if it is in the
281	root	1.2	past. It will not automatically repeat.
282
283			If the C<$interval> is nonzero, then the watcher will always be scheduled
284	root	1.20	to time out at the next C<$at + N * $interval> time.
285	root	1.2
286			This can be used to schedule a callback to run at very regular intervals,
287			as long as the processing time is less then the interval (otherwise
288			obviously events will be skipped).
289
290	root	1.7	Another way to think about it (for the mathematically inclined) is that
291	root	1.20	EV::periodic will try to run the callback at the next possible time where
292	root	1.7	C<$time = $at (mod $interval)>, regardless of any time jumps.
293
294	root	1.20	This periodic timer is based on "wallclock time", that is, if the clock
295			changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at
296	root	1.21	the specified time. This means it will never drift (it might jitter, but
297			it will not drift).
298	root	1.20
299			The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
300	root	1.2
301	root	1.20	=item $w->set ($at, $interval)
302	root	1.11
303	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
304			any time.
305
306
307			=item $w = EV::signal $signal, $callback
308
309			=item $w = EV::signal_ns $signal, $callback
310	root	1.11
311			Call the callback when $signal is received (the signal can be specified
312	root	1.20	by number or by name, just as with kill or %SIG).
313	root	1.2
314	root	1.11	EV will grab the signal for the process (the kernel only allows one
315	root	1.20	component to receive a signal at a time) when you start a signal watcher,
316			and removes it again when you stop it. Perl does the same when you
317			add/remove callbacks to %SIG, so watch out.
318
319			You can have as many signal watchers per signal as you want.
320	root	1.2
321	root	1.20	The C<signal_ns> variant doesn't start (activate) the newly created watcher.
322	root	1.2
323	root	1.20	=item $w->set ($signal)
324	root	1.2
325	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
326			any time.
327
328
329			=item $w = EV::child $pid, $callback
330
331			=item $w = EV::child_ns $pid, $callback
332
333			Call the callback when a status change for pid C<$pid> (or any pid
334			if C<$pid> is 0) has been received. More precisely: when the process
335			receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
336			changed/zombie children and call the callback.
337
338			Unlike all other callbacks, this callback will be called with an
339			additional third argument which is the exit status. See the C<waitpid>
340			function for details.
341
342			You can have as many pid watchers per pid as you want.
343
344			The C<child_ns> variant doesn't start (activate) the newly created watcher.
345
346			=item $w->set ($pid)
347	root	1.1
348	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
349			any time.
350	root	1.2
351
352	root	1.20	=item $w = EV::idle $callback
353	root	1.2
354	root	1.20	=item $w = EV::idle_ns $callback
355	root	1.2
356	root	1.20	Call the callback when there are no pending io, timer/periodic, signal or
357			child events, i.e. when the process is idle.
358	root	1.2
359	root	1.20	The process will not block as long as any idle watchers are active, and
360			they will be called repeatedly until stopped.
361	root	1.2
362	root	1.20	The C<idle_ns> variant doesn't start (activate) the newly created watcher.
363	root	1.2
364
365	root	1.20	=item $w = EV::prepare $callback
366	root	1.1
367	root	1.20	=item $w = EV::prepare_ns $callback
368	root	1.1
369	root	1.20	Call the callback just before the process would block. You can still
370			create/modify any watchers at this point.
371	root	1.1
372	root	1.20	See the EV::check watcher, below, for explanations and an example.
373	root	1.2
374	root	1.20	The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
375	root	1.2
376
377	root	1.20	=item $w = EV::check $callback
378	root	1.2
379	root	1.20	=item $w = EV::check_ns $callback
380	root	1.10
381	root	1.20	Call the callback just after the process wakes up again (after it has
382			gathered events), but before any other callbacks have been invoked.
383	root	1.10
384	root	1.20	This is used to integrate other event-based software into the EV
385			mainloop: You register a prepare callback and in there, you create io and
386			timer watchers as required by the other software. Here is a real-world
387			example of integrating Net::SNMP (with some details left out):
388	root	1.10
389	root	1.20	our @snmp_watcher;
390	root	1.2
391	root	1.20	our $snmp_prepare = EV::prepare sub {
392			# do nothing unless active
393			$dispatcher->{_event_queue_h}
394			or return;
395	root	1.2
396	root	1.20	# make the dispatcher handle any outstanding stuff
397	root	1.2
398	root	1.20	# create an IO watcher for each and every socket
399			@snmp_watcher = (
400			(map { EV::io $_, EV::READ, sub { } }
401			keys %{ $dispatcher->{_descriptors} }),
402			);
403	root	1.2
404	root	1.20	# if there are any timeouts, also create a timer
405			push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
406			if $event->[Net::SNMP::Dispatcher::_ACTIVE];
407			};
408	root	1.2
409	root	1.20	The callbacks are irrelevant, the only purpose of those watchers is
410			to wake up the process as soon as one of those events occurs (socket
411			readable, or timer timed out). The corresponding EV::check watcher will then
412			clean up:
413	root	1.2
414	root	1.20	our $snmp_check = EV::check sub {
415			# destroy all watchers
416			@snmp_watcher = ();
417	root	1.2
418	root	1.20	# make the dispatcher handle any new stuff
419			};
420	root	1.2
421	root	1.20	The callbacks of the created watchers will not be called as the watchers
422			are destroyed before this cna happen (remember EV::check gets called
423			first).
424	root	1.2
425	root	1.20	The C<check_ns> variant doesn't start (activate) the newly created watcher.
426	root	1.1
427			=back
428
429	root	1.13	=head1 THREADS
430
431			Threads are not supported by this in any way. Perl pseudo-threads is evil
432	root	1.20	stuff and must die.
433	root	1.13
434	root	1.1	=cut
435
436	root	1.8	our $DIED = sub {
437			warn "EV: error in callback (ignoring): $@";
438			};
439
440	root	1.14	init;
441	root	1.1
442	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
443
444	root	1.1	1;
445
446	root	1.3	=head1 SEE ALSO
447
448	root	1.20	L<EV::DNS>, L<EV::AnyEvent>.
449	root	1.3
450	root	1.1	=head1 AUTHOR
451
452			Marc Lehmann <schmorp@schmorp.de>
453			http://home.schmorp.de/
454
455			=cut
456