cvsroot/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 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 3) and EV::MINPRI (default
-3). 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.

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.23
Committed:	Fri Nov 2 20:21:33 2007 UTC (18 years, 11 months ago) by root
Branch:	MAIN
Changes since 1.22:	+19 -3 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	root	1.23	object is destroyed, so you I<need> to keep the watcher objects returned by
156	root	1.20	the constructors.
157
158	root	1.23	Also, all methods changing some aspect of a watcher (->set, ->priority,
159			->fh and so on) automatically stop and start it again if it is active,
160			which means pending events get lost.
161
162	root	1.20	=head2 WATCHER TYPES
163
164			Now lets move to the existing watcher types and asociated methods.
165
166			The following methods are available for all watchers. Then followes a
167			description of each watcher constructor (EV::io, EV::timer, EV::periodic,
168			EV::signal, EV::child, EV::idle, EV::prepare and EV::check), followed by
169			any type-specific methods (if any).
170
171			=over 4
172	root	1.2
173	root	1.20	=item $w->start
174
175			Starts a watcher if it isn't active already. Does nothing to an already
176			active watcher. By default, all watchers start out in the active state
177			(see the description of the C<_ns> variants if you need stopped watchers).
178
179			=item $w->stop
180	root	1.2
181	root	1.20	Stop a watcher if it is active. Also clear any pending events (events that
182			have been received but that didn't yet result in a callback invocation),
183			regardless of wether the watcher was active or not.
184	root	1.2
185	root	1.20	=item $bool = $w->is_active
186	root	1.2
187	root	1.20	Returns true if the watcher is active, false otherwise.
188
189			=item $current_cb = $w->cb
190
191			=item $old_cb = $w->cb ($new_cb)
192
193	root	1.23	Queries the callback on the watcher and optionally changes it. You can do
194			this at any time without the watcher restarting.
195
196			=item $current_priority = $w->priority
197
198			=item $old_priority = $w->priority ($new_priority)
199
200			Queries the priority on the watcher and optionally changes it. Pending
201			watchers with higher priority will be invoked first. The valid range of
202			priorities lies between EV::MAXPRI (default 3) and EV::MINPRI (default
203			-3). If the priority is outside this range it will automatically be
204			normalised to the nearest valid priority.
205
206			The default priority of any newly-created weatcher is 0.
207	root	1.20
208			=item $w->trigger ($revents)
209
210			Call the callback now with the given event mask.
211
212
213			=item $w = EV::io $fileno_or_fh, $eventmask, $callback
214	root	1.2
215	root	1.20	=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
216	root	1.7
217	root	1.20	As long as the returned watcher object is alive, call the C<$callback>
218			when the events specified in C<$eventmask>.
219	root	1.2
220	root	1.20	The $eventmask can be one or more of these constants ORed together:
221	root	1.2
222			EV::READ wait until read() wouldn't block anymore
223			EV::WRITE wait until write() wouldn't block anymore
224	root	1.7
225	root	1.20	The C<io_ns> variant doesn't start (activate) the newly created watcher.
226	root	1.2
227	root	1.20	=item $w->set ($fileno_or_fh, $eventmask)
228	root	1.10
229	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be
230			called at any time.
231	root	1.10
232	root	1.20	=item $current_fh = $w->fh
233
234			=item $old_fh = $w->fh ($new_fh)
235
236			Returns the previously set filehandle and optionally set a new one.
237	root	1.10
238	root	1.20	=item $current_eventmask = $w->events
239
240			=item $old_eventmask = $w->events ($new_eventmask)
241	root	1.10
242	root	1.20	Returns the previously set event mask and optionally set a new one.
243	root	1.10
244
245	root	1.20	=item $w = EV::timer $after, $repeat, $callback
246	root	1.2
247	root	1.20	=item $w = EV::timer_ns $after, $repeat, $callback
248	root	1.2
249	root	1.20	Calls the callback after C<$after> seconds. If C<$repeat> is non-zero,
250			the timer will be restarted (with the $repeat value as $after) after the
251			callback returns.
252	root	1.2
253	root	1.20	This means that the callback would be called roughly after C<$after>
254			seconds, and then every C<$repeat> seconds. "Roughly" because the time of
255			callback processing is not taken into account, so the timer will slowly
256			drift. If that isn't acceptable, look at EV::periodic.
257	root	1.2
258	root	1.20	The timer is based on a monotonic clock, that is if somebody is sitting
259			in front of the machine while the timer is running and changes the system
260			clock, the timer will nevertheless run (roughly) the same time.
261	root	1.2
262	root	1.20	The C<timer_ns> variant doesn't start (activate) the newly created watcher.
263
264			=item $w->set ($after, $repeat)
265
266			Reconfigures the watcher, see the constructor above for details. Can be at
267			any time.
268
269			=item $w->again
270
271			Similar to the C<start> method, but has special semantics for repeating timers:
272
273			If the timer is active and repeating, reset the timeout to occur
274			C<$repeat> seconds after now.
275
276			If the timer is active and non-repeating, it will be stopped.
277
278			If the timer is in active and repeating, start it.
279
280			Otherwise do nothing.
281
282			This behaviour is useful when you have a timeout for some IO
283			operation. You create a timer object with the same value for C<$after> and
284			C<$repeat>, and then, in the read/write watcher, run the C<again> method
285			on the timeout.
286
287
288			=item $w = EV::periodic $at, $interval, $callback
289
290			=item $w = EV::periodic_ns $at, $interval, $callback
291	root	1.2
292			Similar to EV::timer, but the time is given as an absolute point in time
293			(C<$at>), plus an optional C<$interval>.
294
295			If the C<$interval> is zero, then the callback will be called at the time
296	root	1.20	C<$at> if that is in the future, or as soon as possible if it is in the
297	root	1.2	past. It will not automatically repeat.
298
299			If the C<$interval> is nonzero, then the watcher will always be scheduled
300	root	1.20	to time out at the next C<$at + N * $interval> time.
301	root	1.2
302			This can be used to schedule a callback to run at very regular intervals,
303			as long as the processing time is less then the interval (otherwise
304			obviously events will be skipped).
305
306	root	1.7	Another way to think about it (for the mathematically inclined) is that
307	root	1.20	EV::periodic will try to run the callback at the next possible time where
308	root	1.7	C<$time = $at (mod $interval)>, regardless of any time jumps.
309
310	root	1.20	This periodic timer is based on "wallclock time", that is, if the clock
311			changes (C<ntp>, C<date -s> etc.), then the timer will nevertheless run at
312	root	1.21	the specified time. This means it will never drift (it might jitter, but
313			it will not drift).
314	root	1.20
315			The C<periodic_ns> variant doesn't start (activate) the newly created watcher.
316	root	1.2
317	root	1.20	=item $w->set ($at, $interval)
318	root	1.11
319	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
320			any time.
321
322
323			=item $w = EV::signal $signal, $callback
324
325			=item $w = EV::signal_ns $signal, $callback
326	root	1.11
327			Call the callback when $signal is received (the signal can be specified
328	root	1.20	by number or by name, just as with kill or %SIG).
329	root	1.2
330	root	1.11	EV will grab the signal for the process (the kernel only allows one
331	root	1.20	component to receive a signal at a time) when you start a signal watcher,
332			and removes it again when you stop it. Perl does the same when you
333			add/remove callbacks to %SIG, so watch out.
334
335			You can have as many signal watchers per signal as you want.
336	root	1.2
337	root	1.20	The C<signal_ns> variant doesn't start (activate) the newly created watcher.
338	root	1.2
339	root	1.20	=item $w->set ($signal)
340	root	1.2
341	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
342			any time.
343
344	root	1.22	=item $current_signum = $w->signal
345
346			=item $old_signum = $w->signal ($new_signal)
347
348			Returns the previously set signal (always as a number not name) and
349			optionally set a new one.
350
351	root	1.20
352			=item $w = EV::child $pid, $callback
353
354			=item $w = EV::child_ns $pid, $callback
355
356			Call the callback when a status change for pid C<$pid> (or any pid
357			if C<$pid> is 0) has been received. More precisely: when the process
358			receives a SIGCHLD, EV will fetch the outstanding exit/wait status for all
359			changed/zombie children and call the callback.
360
361			Unlike all other callbacks, this callback will be called with an
362			additional third argument which is the exit status. See the C<waitpid>
363			function for details.
364
365			You can have as many pid watchers per pid as you want.
366
367			The C<child_ns> variant doesn't start (activate) the newly created watcher.
368
369			=item $w->set ($pid)
370	root	1.1
371	root	1.20	Reconfigures the watcher, see the constructor above for details. Can be at
372			any time.
373	root	1.2
374	root	1.22	=item $current_pid = $w->pid
375
376			=item $old_pid = $w->pid ($new_pid)
377
378			Returns the previously set process id and optionally set a new one.
379
380	root	1.2
381	root	1.20	=item $w = EV::idle $callback
382	root	1.2
383	root	1.20	=item $w = EV::idle_ns $callback
384	root	1.2
385	root	1.20	Call the callback when there are no pending io, timer/periodic, signal or
386			child events, i.e. when the process is idle.
387	root	1.2
388	root	1.20	The process will not block as long as any idle watchers are active, and
389			they will be called repeatedly until stopped.
390	root	1.2
391	root	1.20	The C<idle_ns> variant doesn't start (activate) the newly created watcher.
392	root	1.2
393
394	root	1.20	=item $w = EV::prepare $callback
395	root	1.1
396	root	1.20	=item $w = EV::prepare_ns $callback
397	root	1.1
398	root	1.20	Call the callback just before the process would block. You can still
399			create/modify any watchers at this point.
400	root	1.1
401	root	1.20	See the EV::check watcher, below, for explanations and an example.
402	root	1.2
403	root	1.20	The C<prepare_ns> variant doesn't start (activate) the newly created watcher.
404	root	1.2
405
406	root	1.20	=item $w = EV::check $callback
407	root	1.2
408	root	1.20	=item $w = EV::check_ns $callback
409	root	1.10
410	root	1.20	Call the callback just after the process wakes up again (after it has
411			gathered events), but before any other callbacks have been invoked.
412	root	1.10
413	root	1.20	This is used to integrate other event-based software into the EV
414			mainloop: You register a prepare callback and in there, you create io and
415			timer watchers as required by the other software. Here is a real-world
416			example of integrating Net::SNMP (with some details left out):
417	root	1.10
418	root	1.20	our @snmp_watcher;
419	root	1.2
420	root	1.20	our $snmp_prepare = EV::prepare sub {
421			# do nothing unless active
422			$dispatcher->{_event_queue_h}
423			or return;
424	root	1.2
425	root	1.20	# make the dispatcher handle any outstanding stuff
426	root	1.2
427	root	1.20	# create an IO watcher for each and every socket
428			@snmp_watcher = (
429			(map { EV::io $_, EV::READ, sub { } }
430			keys %{ $dispatcher->{_descriptors} }),
431			);
432	root	1.2
433	root	1.20	# if there are any timeouts, also create a timer
434			push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
435			if $event->[Net::SNMP::Dispatcher::_ACTIVE];
436			};
437	root	1.2
438	root	1.20	The callbacks are irrelevant, the only purpose of those watchers is
439			to wake up the process as soon as one of those events occurs (socket
440			readable, or timer timed out). The corresponding EV::check watcher will then
441			clean up:
442	root	1.2
443	root	1.20	our $snmp_check = EV::check sub {
444			# destroy all watchers
445			@snmp_watcher = ();
446	root	1.2
447	root	1.20	# make the dispatcher handle any new stuff
448			};
449	root	1.2
450	root	1.20	The callbacks of the created watchers will not be called as the watchers
451			are destroyed before this cna happen (remember EV::check gets called
452			first).
453	root	1.2
454	root	1.20	The C<check_ns> variant doesn't start (activate) the newly created watcher.
455	root	1.1
456			=back
457
458	root	1.13	=head1 THREADS
459
460			Threads are not supported by this in any way. Perl pseudo-threads is evil
461	root	1.20	stuff and must die.
462	root	1.13
463	root	1.1	=cut
464
465	root	1.8	our $DIED = sub {
466			warn "EV: error in callback (ignoring): $@";
467			};
468
469	root	1.14	init;
470	root	1.1
471	root	1.4	push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
472
473	root	1.1	1;
474
475	root	1.3	=head1 SEE ALSO
476
477	root	1.20	L<EV::DNS>, L<EV::AnyEvent>.
478	root	1.3
479	root	1.1	=head1 AUTHOR
480
481			Marc Lehmann <schmorp@schmorp.de>
482			http://home.schmorp.de/
483
484			=cut
485