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 $current_signum = $w->signal

=item $old_signum = $w->signal ($new_signal)

Returns the previously set signal (always as a number not name) and
optionally set a new one.


=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 $current_pid = $w->pid

=item $old_pid = $w->pid ($new_pid)

Returns the previously set process id and optionally set a new one.


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