[ViewVC] Annotation of: cvs/EV/README

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

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, 0, 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

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

BASIC INTERFACE
    $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.

    $time = EV::time
        Returns the current time in (fractional) seconds since the epoch.

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

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

    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)

    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.

  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 "_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 *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.

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

    $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 "_ns" variants if you need
        stopped watchers).

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

    $bool = $w->is_active
        Returns true if the watcher is active, false otherwise.

    $current_data = $w->data
    $old_data = $w->data ($new_data)
        Queries a freely usable data scalar on the watcher and optionally
        changes it. This is a way to associate custom data with a watcher:

           my $w = EV::timer 60, 0, sub {
              warn $_[0]->data;
           };
           $w->data ("print me!");

    $current_cb = $w->cb
    $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.

    $current_priority = $w->priority
    $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.

    $w->trigger ($revents)
        Call the callback *now* with the given event mask.

    $w = EV::io $fileno_or_fh, $eventmask, $callback
    $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
        As long as the returned watcher object is alive, call the $callback
        when the events specified in $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 "io_ns" variant doesn't start (activate) the newly created
        watcher.

    $w->set ($fileno_or_fh, $eventmask)
        Reconfigures the watcher, see the constructor above for details. Can
        be called at any time.

    $current_fh = $w->fh
    $old_fh = $w->fh ($new_fh)
        Returns the previously set filehandle and optionally set a new one.

    $current_eventmask = $w->events
    $old_eventmask = $w->events ($new_eventmask)
        Returns the previously set event mask and optionally set a new one.

    $w = EV::timer $after, $repeat, $callback
    $w = EV::timer_ns $after, $repeat, $callback
        Calls the callback after $after seconds. If $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 $after
        seconds, and then every $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 "timer_ns" variant doesn't start (activate) the newly created
        watcher.

    $w->set ($after, $repeat)
        Reconfigures the watcher, see the constructor above for details. Can
        be at any time.

    $w->again
        Similar to the "start" method, but has special semantics for
        repeating timers:

        If the timer is active and repeating, reset the timeout to occur
        $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 $after
        and $repeat, and then, in the read/write watcher, run the "again"
        method on the timeout.

    $w = EV::periodic $at, $interval, $reschedule_cb, $callback
    $w = EV::periodic_ns $at, $interval, $reschedule_cb, $callback
        Similar to EV::timer, but is not based on relative timeouts but on
        absolute times. Apart from creating "simple" timers that trigger
        "at" the specified time, it can also be used for non-drifting
        absolute timers and more complex, cron-like, setups that are not
        adversely affected by time jumps (i.e. when the system clock is
        changed by explicit date -s or other means such as ntpd). It is also
        the most complex watcher type in EV.

        It has three distinct "modes":

        * absolute timer ($interval = $reschedule_cb = 0)
            This time simply fires at the wallclock time $at and doesn't
            repeat. It will not adjust when a time jump occurs, that is, if
            it is to be run at January 1st 2011 then it will run when the
            system time reaches or surpasses this time.

        * non-repeating interval timer ($interval > 0, $reschedule_cb = 0)
            In this mode the watcher will always be scheduled to time out at
            the next "$at + N * $interval" time (for some integer N) and
            then repeat, regardless of any time jumps.

            This can be used to create timers that do not drift with respect
            to system time:

               my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };

            That doesn't mean there will always be 3600 seconds in between
            triggers, but only that the the clalback will be called when the
            system time shows a full hour (UTC).

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

        * manual reschedule mode ($reschedule_cb = coderef)
            In this mode $interval and $at are both being ignored. Instead,
            each time the periodic watcher gets scheduled, the first
            callback ($reschedule_cb) will be called with the watcher as
            first, and the current time as second argument.

            *This callback MUST NOT stop or destroy this or any other
            periodic watcher, ever*. If you need to stop it, return 1e30 and
            stop it afterwards.

            It must return the next time to trigger, based on the passed
            time value (that is, the lowest time value larger than to the
            second argument). It will usually be called just before the
            callback will be triggered, but might be called at other times,
            too.

            This can be used to create very complex timers, such as a timer
            that triggers on each midnight, local time (actually 24 hours
            after the last midnight, to keep the example simple. If you know
            a way to do it correctly in about the same space (without
            requiring elaborate modules), drop me a note :):

               my $daily = EV::periodic 0, 0, sub {
                  my ($w, $now) = @_;

                  use Time::Local ();
                  my (undef, undef, undef, $d, $m, $y) = localtime $now;
                  86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
               }, sub {
                  print "it's midnight or likely shortly after, now\n";
               };

        The "periodic_ns" variant doesn't start (activate) the newly created
        watcher.

    $w->set ($at, $interval, $reschedule_cb)
        Reconfigures the watcher, see the constructor above for details. Can
        be at any time.

    $w->again
        Simply stops and starts the watcher again.

    $w = EV::signal $signal, $callback
    $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 "signal_ns" variant doesn't start (activate) the newly created
        watcher.

    $w->set ($signal)
        Reconfigures the watcher, see the constructor above for details. Can
        be at any time.

    $current_signum = $w->signal
    $old_signum = $w->signal ($new_signal)
        Returns the previously set signal (always as a number not name) and
        optionally set a new one.

    $w = EV::child $pid, $callback
    $w = EV::child_ns $pid, $callback
        Call the callback when a status change for pid $pid (or any pid if
        $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 "rstatus" and "rpid"
        methods on the watcher object.

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

        The "child_ns" variant doesn't start (activate) the newly created
        watcher.

    $w->set ($pid)
        Reconfigures the watcher, see the constructor above for details. Can
        be at any time.

    $current_pid = $w->pid
    $old_pid = $w->pid ($new_pid)
        Returns the previously set process id and optionally set a new one.

    $exit_status = $w->rstatus
        Return the exit/wait status (as returned by waitpid, see the waitpid
        entry in perlfunc).

    $pid = $w->rpid
        Return the pid of the awaited child (useful when you have installed
        a watcher for all pids).

    $w = EV::idle $callback
    $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 "idle_ns" variant doesn't start (activate) the newly created
        watcher.

    $w = EV::prepare $callback
    $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 "prepare_ns" variant doesn't start (activate) the newly created
        watcher.

    $w = EV::check $callback
    $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 "check_ns" variant doesn't start (activate) the newly created
        watcher.

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

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

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

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