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) = @_;
     # my $pid = $w->rpid;
     my $status = $w->rstatus;
  };
  
  # 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.5';
   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 destroyed, so you I<need> to keep the watcher objects returned by
the constructors.

Also, all methods changing some aspect of a watcher (->set, ->priority,
->fh and so on) automatically stop and start it again if it is active,
which means pending events get lost.

=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 can do
this at any time without the watcher restarting.

=item $current_priority = $w->priority

=item $old_priority = $w->priority ($new_priority)

Queries the priority on the watcher and optionally changes it. Pending
watchers with higher priority will be invoked first. The valid range of
priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
-2). If the priority is outside this range it will automatically be
normalised to the nearest valid priority.

The default priority of any newly-created weatcher is 0.

=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.

You can access both status and pid by using the C<rstatus> and C<rpid>
methods on the watcher object.

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 $exit_status = $w->rstatus

Return the exit/wait status (as returned by waitpid, see the waitpid entry
in perlfunc).

=item $pid = $w->rpid

Return the pid of the awaited child (useful when you have installed a
watcher for all pids).


=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): $@";
};

default_loop
   or die 'EV: cannot initialise libev backend. bad $ENV{LIBEV_METHODS}?';

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