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.

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.20
Committed:	Thu Nov 1 17:17:32 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.19:	+258 -129 lines
Log Message:	created new documentation
#	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			the specified time.
297
298			The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
299	root	1.2
300	root	1.20	=item $w->set ($at, $interval)
301	root	1.11
302	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
303			any time.
304
305
306			=item $w = EV::signal $signal, $callback
307
308			=item $w = EV::signal_ns $signal, $callback
309	root	1.11
310			Call the callback when $signal is received (the signal can be specified
311	root	1.20	by number or by name, just as with kill or %SIG).
312	root	1.2
313	root	1.11	EV will grab the signal for the process (the kernel only allows one
314	root	1.20	component to receive a signal at a time) when you start a signal watcher,
315			and removes it again when you stop it. Perl does the same when you
316			add/remove callbacks to %SIG, so watch out.
317
318			You can have as many signal watchers per signal as you want.
319	root	1.2
320	root	1.20	The C<signal_ns> variant doesn't start (activate) the newly created watcher.
321	root	1.2
322	root	1.20	=item $w->set ($signal)
323	root	1.2
324	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
325			any time.
326
327
328			=item $w = EV::child $pid, $callback
329
330			=item $w = EV::child_ns $pid, $callback
331
332			Call the callback when a status change for pid C<$pid> (or any pid
333			if C<$pid> is 0) has been received. More precisely: when the process
334			receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
335			changed/zombie children and call the callback.
336
337			Unlike all other callbacks, this callback will be called with an
338			additional third argument which is the exit status. See the C<waitpid>
339			function for details.
340
341			You can have as many pid watchers per pid as you want.
342
343			The C<child_ns> variant doesn't start (activate) the newly created watcher.
344
345			=item $w->set ($pid)
346	root	1.1
347	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
348			any time.
349	root	1.2
350
351	root	1.20	=item $w = EV::idle $callback
352	root	1.2
353	root	1.20	=item $w = EV::idle_ns $callback
354	root	1.2
355	root	1.20	Call the callback when there are no pending io, timer/periodic, signal or
356			child events, i.e. when the process is idle.
357	root	1.2
358	root	1.20	The process will not block as long as any idle watchers are active, and
359			they will be called repeatedly until stopped.
360	root	1.2
361	root	1.20	The C<idle_ns> variant doesn't start (activate) the newly created watcher.
362	root	1.2
363
364	root	1.20	=item $w = EV::prepare $callback
365	root	1.1
366	root	1.20	=item $w = EV::prepare_ns $callback
367	root	1.1
368	root	1.20	Call the callback just before the process would block. You can still
369			create/modify any watchers at this point.
370	root	1.1
371	root	1.20	See the EV::check watcher, below, for explanations and an example.
372	root	1.2
373	root	1.20	The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
374	root	1.2
375
376	root	1.20	=item $w = EV::check $callback
377	root	1.2
378	root	1.20	=item $w = EV::check_ns $callback
379	root	1.10
380	root	1.20	Call the callback just after the process wakes up again (after it has
381			gathered events), but before any other callbacks have been invoked.
382	root	1.10
383	root	1.20	This is used to integrate other event-based software into the EV
384			mainloop: You register a prepare callback and in there, you create io and
385			timer watchers as required by the other software. Here is a real-world
386			example of integrating Net::SNMP (with some details left out):
387	root	1.10
388	root	1.20	our @snmp_watcher;
389	root	1.2
390	root	1.20	our $snmp_prepare = EV::prepare sub {
391			# do nothing unless active
392			$dispatcher->{_event_queue_h}
393			or return;
394	root	1.2
395	root	1.20	# make the dispatcher handle any outstanding stuff
396	root	1.2
397	root	1.20	# create an IO watcher for each and every socket
398			@snmp_watcher = (
399			(map { EV::io $_, EV::READ, sub { } }
400			keys %{ $dispatcher->{_descriptors} }),
401			);
402	root	1.2
403	root	1.20	# if there are any timeouts, also create a timer
404			push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
405			if $event->[Net::SNMP::Dispatcher::_ACTIVE];
406			};
407	root	1.2
408	root	1.20	The callbacks are irrelevant, the only purpose of those watchers is
409			to wake up the process as soon as one of those events occurs (socket
410			readable, or timer timed out). The corresponding EV::check watcher will then
411			clean up:
412	root	1.2
413	root	1.20	our $snmp_check = EV::check sub {
414			# destroy all watchers
415			@snmp_watcher = ();
416	root	1.2
417	root	1.20	# make the dispatcher handle any new stuff
418			};
419	root	1.2
420	root	1.20	The callbacks of the created watchers will not be called as the watchers
421			are destroyed before this cna happen (remember EV::check gets called
422			first).
423	root	1.2
424	root	1.20	The C<check_ns> variant doesn't start (activate) the newly created watcher.
425	root	1.1
426			=back
427
428	root	1.13	=head1 THREADS
429
430			Threads are not supported by this in any way. Perl pseudo-threads is evil
431	root	1.20	stuff and must die.
432	root	1.13
433	root	1.1	=cut
434
435	root	1.8	our $DIED = sub {
436			warn "EV: error in callback (ignoring): $@";
437			};
438
439	root	1.14	init;
440	root	1.1
441	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
442
443	root	1.1	1;
444
445	root	1.3	=head1 SEE ALSO
446
447	root	1.20	L<EV::DNS>, L<EV::AnyEvent>.
448	root	1.3
449	root	1.1	=head1 AUTHOR
450
451			Marc Lehmann <schmorp@schmorp.de>
452			http://home.schmorp.de/
453
454			=cut
455