[ViewVC] Annotation of: cvs/EV/README

NAME
    EV - perl interface to libevent, monkey.org/~provos/libevent/

SYNOPSIS
      use EV;
  
      # TIMER
  
      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::timer_abs 0, 60, sub {
         warn "is called every minute, on the minute, exactly";
      };
  
      # IO
  
      my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub {
         my ($w, $revents) = @_; # all callbacks get the watcher object and event mask
         if ($revents & EV::TIMEOUT) {
            warn "nothing received on stdin for 10 seconds, retrying";
         } else {
            warn "stdin is readable, you entered: ", <STDIN>;
         }
      };
      $w->timeout (10);
  
      my $w = EV::timed_io \*STDIN, EV::READ, 30, sub {
         my ($w, $revents) = @_;
         if ($revents & EV::TIMEOUT) {
            warn "nothing entered within 30 seconds, bye bye.\n";
            $w->stop;
         } else {
            my $line = <STDIN>;
            warn "you entered something, you again have 30 seconds.\n";
         }
      };
  
      # 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::dispatch; # loop as long as watchers are active
      EV::loop;     # the same thing
      EV::loop EV::LOOP_ONESHOT;  # block until some events could be handles
      EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait

DESCRIPTION
    This module provides an interface to libev
    (<http://software.schmorp.de/pkg/libev.html>). You probably should
    acquaint yourself with its documentation and source code to be able to
    use this module fully.

BASIC INTERFACE
    $EV::NPRI
        How many priority levels are available.

    $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::now
        Returns the time in (fractional) seconds since the epoch.

    $version = EV::version
    $method = EV::method
        Return version string and event polling method used.

    EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
    EV::loopexit $after
        Exit any active loop or dispatch after $after seconds or immediately
        if $after is missing or zero.

    EV::dispatch
        Same as "EV::loop 0".

    EV::event $callback
        Creates a new event watcher waiting for nothing, calling the given
        callback.

    my $w = EV::io $fileno_or_fh, $eventmask, $callback
    my $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 happen. Initially, the
        timeout is disabled.

        You can additionall set a timeout to occur on the watcher, but note
        that this timeout will not be reset when you get an I/O event in the
        EV::PERSIST case, and reaching a timeout will always stop the
        watcher even in the EV::PERSIST case.

        If you want a timeout to occur only after a specific time of
        inactivity, set a repeating timeout and do NOT use EV::PERSIST.

        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
          EV::PERSIST  stay active after a (non-timeout) event occured

        The "io_ns" variant doesn't add/start the newly created watcher.

    my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
    my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
        Same as "io" and "io_ns", but also specifies a timeout (as if there
        was a call to "$w->timeout ($timout, 1)". The persist flag is not
        allowed and will automatically be cleared. The watcher will be
        restarted after each event.

        If the timeout is zero or undef, no timeout will be set, and a
        normal watcher (with the persist flag set!) will be created.

        This has the effect of timing out after the specified period of
        inactivity has happened.

        Due to the design of libevent, this is also relatively inefficient,
        having one or two io watchers and a separate timeout watcher that
        you reset on activity (by calling its "start" method) is usually
        more efficient.

    my $w = EV::timer $after, $repeat, $callback
    my $w = EV::timer_ns $after, $repeat, $callback
        Calls the callback after $after seconds. If $repeat is true, the
        timer will be restarted after the callback returns. This means that
        the callback would be called roughly every $after seconds, prolonged
        by the time the callback takes.

        The "timer_ns" variant doesn't add/start the newly created watcher.

    my $w = EV::timer_abs $at, $interval, $callback
    my $w = EV::timer_abs_ns $at, $interval, $callback
        Similar to EV::timer, but the time is given as an absolute point in
        time ($at), plus an optional $interval.

        If the $interval is zero, then the callback will be called at the
        time $at if that is in the future, or as soon as possible if its in
        the past. It will not automatically repeat.

        If the $interval is nonzero, then the watcher will always be
        scheduled to time out at the next "$at + integer * $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 "timer_abs" will try to tun the callback at the next possible
        time where "$time = $at (mod $interval)", regardless of any time
        jumps.

        The "timer_abs_ns" variant doesn't add/start the newly created
        watcher.

    my $w = EV::signal $signal, $callback
    my $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). Signal
        watchers are persistent no natter what.

        EV will grab the signal for the process (the kernel only allows one
        component to receive signals) when you start a signal watcher, and
        removes it again when you stop it. Pelr does the same when you
        add/remove callbacks to %SIG, so watch out.

        Unfortunately, only one handler can be registered per signal. Screw
        libevent.

        The "signal_ns" variant doesn't add/start the newly created watcher.

THE EV::Event CLASS
    All EV functions creating an event watcher (designated by "my $w ="
    above) support the following methods on the returned watcher object:

    $w->add ($timeout)
        Stops and (re-)starts the event watcher, setting the optional
        timeout to the given value, or clearing the timeout if none is
        given.

    $w->start
        Stops and (re-)starts the event watcher without touching the
        timeout.

    $w->del
    $w->stop
        Stop the event watcher if it was started.

    $current_callback = $w->cb
    $old_callback = $w->cb ($new_callback)
        Return the previously set callback and optionally set a new one.

    $current_fh = $w->fh
    $old_fh = $w->fh ($new_fh)
        Returns the previously set filehandle and optionally set a new one
        (also clears the EV::SIGNAL flag when setting a filehandle).

    $current_signal = $w->signal
    $old_signal = $w->signal ($new_signal)
        Returns the previously set signal number and optionally set a new
        one (also sets the EV::SIGNAL flag when setting a signal).

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

    $w->timeout ($after, $repeat)
        Resets the timeout (see "EV::timer" for details).

    $w->timeout_abs ($at, $interval)
        Resets the timeout (see "EV::timer_abs" for details).

    $w->priority_set ($priority)
        Set the priority of the watcher to $priority (0 <= $priority <
        $EV::NPRI).

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

SEE ALSO
      L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
      L<EV::AnyEvent>.

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

Revision:	1.5
Committed:	Thu Nov 1 13:33:12 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.4:	+18 -23 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	NAME
2	root	1.2	EV - perl interface to libevent, monkey.org/~provos/libevent/
3	root	1.1
4	root	1.2	SYNOPSIS
5	root	1.4	use EV;
6
7			# TIMER
8
9			my $w = EV::timer 2, 0, sub {
10			warn "is called after 2s";
11			};
12
13			my $w = EV::timer 2, 1, sub {
14			warn "is called roughly every 2s (repeat = 1)";
15			};
16
17			undef $w; # destroy event watcher again
18
19			my $w = EV::timer_abs 0, 60, sub {
20			warn "is called every minute, on the minute, exactly";
21			};
22
23			# IO
24
25			my $w = EV::io \*STDIN, EV::READ \| EV::PERSIST, sub {
26	root	1.5	my ($w, $revents) = @_; # all callbacks get the watcher object and event mask
27			if ($revents & EV::TIMEOUT) {
28	root	1.4	warn "nothing received on stdin for 10 seconds, retrying";
29			} else {
30			warn "stdin is readable, you entered: ", <STDIN>;
31			}
32			};
33			$w->timeout (10);
34
35			my $w = EV::timed_io \*STDIN, EV::READ, 30, sub {
36	root	1.5	my ($w, $revents) = @_;
37			if ($revents & EV::TIMEOUT) {
38	root	1.4	warn "nothing entered within 30 seconds, bye bye.\n";
39			$w->stop;
40			} else {
41			my $line = <STDIN>;
42			warn "you entered something, you again have 30 seconds.\n";
43			}
44			};
45
46			# SIGNALS
47
48			my $w = EV::signal 'QUIT', sub {
49			warn "sigquit received\n";
50			};
51
52			my $w = EV::signal 3, sub {
53			warn "sigquit received (this is GNU/Linux, right?)\n";
54			};
55	root	1.5
56			# CHILD/PID STATUS CHANGES
57
58			my $w = EV::child 666, sub {
59			my ($w, $revents, $status) = @_;
60			};
61	root	1.4
62			# MAINLOOP
63			EV::dispatch; # loop as long as watchers are active
64			EV::loop; # the same thing
65	root	1.5	EV::loop EV::LOOP_ONESHOT; # block until some events could be handles
66	root	1.4	EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
67	root	1.2
68			DESCRIPTION
69	root	1.5	This module provides an interface to libev
70			(<http://software.schmorp.de/pkg/libev.html>). You probably should
71			acquaint yourself with its documentation and source code to be able to
72			use this module fully.
73	root	1.2
74	root	1.3	BASIC INTERFACE
75	root	1.2	$EV::NPRI
76			How many priority levels are available.
77
78	root	1.3	$EV::DIED
79			Must contain a reference to a function that is called when a
80			callback throws an exception (with $@ containing thr error). The
81			default prints an informative message and continues.
82
83			If this callback throws an exception it will be silently ignored.
84
85	root	1.2	$time = EV::now
86			Returns the time in (fractional) seconds since the epoch.
87
88			$version = EV::version
89			$method = EV::method
90			Return version string and event polling method used.
91
92			EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
93			EV::loopexit $after
94			Exit any active loop or dispatch after $after seconds or immediately
95			if $after is missing or zero.
96
97			EV::dispatch
98			Same as "EV::loop 0".
99
100			EV::event $callback
101			Creates a new event watcher waiting for nothing, calling the given
102			callback.
103
104			my $w = EV::io $fileno_or_fh, $eventmask, $callback
105			my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
106			As long as the returned watcher object is alive, call the $callback
107			when the events specified in $eventmask happen. Initially, the
108			timeout is disabled.
109
110	root	1.4	You can additionall set a timeout to occur on the watcher, but note
111	root	1.2	that this timeout will not be reset when you get an I/O event in the
112			EV::PERSIST case, and reaching a timeout will always stop the
113			watcher even in the EV::PERSIST case.
114
115			If you want a timeout to occur only after a specific time of
116			inactivity, set a repeating timeout and do NOT use EV::PERSIST.
117
118			Eventmask can be one or more of these constants ORed together:
119	root	1.1
120	root	1.2	EV::READ wait until read() wouldn't block anymore
121			EV::WRITE wait until write() wouldn't block anymore
122			EV::PERSIST stay active after a (non-timeout) event occured
123
124			The "io_ns" variant doesn't add/start the newly created watcher.
125
126	root	1.4	my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
127			my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
128			Same as "io" and "io_ns", but also specifies a timeout (as if there
129			was a call to "$w->timeout ($timout, 1)". The persist flag is not
130			allowed and will automatically be cleared. The watcher will be
131			restarted after each event.
132
133			If the timeout is zero or undef, no timeout will be set, and a
134			normal watcher (with the persist flag set!) will be created.
135
136			This has the effect of timing out after the specified period of
137			inactivity has happened.
138
139			Due to the design of libevent, this is also relatively inefficient,
140			having one or two io watchers and a separate timeout watcher that
141			you reset on activity (by calling its "start" method) is usually
142			more efficient.
143
144	root	1.2	my $w = EV::timer $after, $repeat, $callback
145			my $w = EV::timer_ns $after, $repeat, $callback
146			Calls the callback after $after seconds. If $repeat is true, the
147			timer will be restarted after the callback returns. This means that
148			the callback would be called roughly every $after seconds, prolonged
149			by the time the callback takes.
150
151			The "timer_ns" variant doesn't add/start the newly created watcher.
152
153			my $w = EV::timer_abs $at, $interval, $callback
154			my $w = EV::timer_abs_ns $at, $interval, $callback
155			Similar to EV::timer, but the time is given as an absolute point in
156			time ($at), plus an optional $interval.
157
158			If the $interval is zero, then the callback will be called at the
159			time $at if that is in the future, or as soon as possible if its in
160			the past. It will not automatically repeat.
161
162			If the $interval is nonzero, then the watcher will always be
163			scheduled to time out at the next "$at + integer * $interval" time.
164
165			This can be used to schedule a callback to run at very regular
166			intervals, as long as the processing time is less then the interval
167			(otherwise obviously events will be skipped).
168
169			Another way to think about it (for the mathematically inclined) is
170			that "timer_abs" will try to tun the callback at the next possible
171			time where "$time = $at (mod $interval)", regardless of any time
172			jumps.
173
174			The "timer_abs_ns" variant doesn't add/start the newly created
175			watcher.
176
177	root	1.4	my $w = EV::signal $signal, $callback
178			my $w = EV::signal_ns $signal, $callback
179			Call the callback when $signal is received (the signal can be
180			specified by number or by name, just as with kill or %SIG). Signal
181			watchers are persistent no natter what.
182
183			EV will grab the signal for the process (the kernel only allows one
184			component to receive signals) when you start a signal watcher, and
185			removes it again when you stop it. Pelr does the same when you
186			add/remove callbacks to %SIG, so watch out.
187
188			Unfortunately, only one handler can be registered per signal. Screw
189			libevent.
190	root	1.2
191			The "signal_ns" variant doesn't add/start the newly created watcher.
192
193			THE EV::Event CLASS
194			All EV functions creating an event watcher (designated by "my $w ="
195			above) support the following methods on the returned watcher object:
196
197			$w->add ($timeout)
198			Stops and (re-)starts the event watcher, setting the optional
199			timeout to the given value, or clearing the timeout if none is
200			given.
201	root	1.1
202	root	1.2	$w->start
203			Stops and (re-)starts the event watcher without touching the
204			timeout.
205	root	1.1
206	root	1.2	$w->del
207			$w->stop
208			Stop the event watcher if it was started.
209	root	1.1
210	root	1.2	$current_callback = $w->cb
211			$old_callback = $w->cb ($new_callback)
212			Return the previously set callback and optionally set a new one.
213	root	1.1
214	root	1.2	$current_fh = $w->fh
215			$old_fh = $w->fh ($new_fh)
216	root	1.4	Returns the previously set filehandle and optionally set a new one
217			(also clears the EV::SIGNAL flag when setting a filehandle).
218
219			$current_signal = $w->signal
220			$old_signal = $w->signal ($new_signal)
221			Returns the previously set signal number and optionally set a new
222			one (also sets the EV::SIGNAL flag when setting a signal).
223	root	1.1
224	root	1.2	$current_eventmask = $w->events
225			$old_eventmask = $w->events ($new_eventmask)
226			Returns the previously set event mask and optionally set a new one.
227	root	1.1
228	root	1.2	$w->timeout ($after, $repeat)
229			Resets the timeout (see "EV::timer" for details).
230	root	1.1
231	root	1.2	$w->timeout_abs ($at, $interval)
232			Resets the timeout (see "EV::timer_abs" for details).
233	root	1.1
234	root	1.2	$w->priority_set ($priority)
235			Set the priority of the watcher to $priority (0 <= $priority <
236			$EV::NPRI).
237	root	1.1
238	root	1.5	THREADS
239			Threads are not supported by this in any way. Perl pseudo-threads is
240			evil and must die.
241	root	1.2
242			SEE ALSO
243			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
244			L<EV::AnyEvent>.
245	root	1.1
246			AUTHOR
247			Marc Lehmann <schmorp@schmorp.de>
248			http://home.schmorp.de/
249