[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, $events) = @_; # all callbacks get the watcher object and event mask
         if ($events & 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, $events) = @_;
         if ($_[1] & 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";
      };
  
      # MAINLOOP
      EV::dispatch; # loop as long as watchers are active
      EV::loop;     # the same thing
      EV::loop EV::LOOP_ONCE;     # 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 libevent
    (<http://monkey.org/~provos/libevent/>). You probably should acquaint
    yourself with its documentation and source code to be able to use this
    module fully.

    Please note thta this module disables the libevent EPOLL method by
    default, see BUGS, below, if you need to enable it.

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

BUGS
    Lots. Libevent itself isn't well tested and rather buggy, and this
    module is quite new at the moment.

    Please note that the epoll method is not, in general, reliable in
    programs that use fork (even if no libveent calls are being made in the
    forked process). If your program behaves erratically, try setting the
    environment variable "EVENT_NOEPOLL" first when running the program.

    In general, if you fork, then you can only use the EV module in one of
    the children.

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.4
Committed:	Mon Oct 29 19:53:21 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_03
Changes since 1.3:	+95 -40 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			my ($w, $events) = @_; # all callbacks get the watcher object and event mask
27			if ($events & EV::TIMEOUT) {
28			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			my ($w, $events) = @_;
37			if ($_[1] & EV::TIMEOUT) {
38			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
56			# MAINLOOP
57			EV::dispatch; # loop as long as watchers are active
58			EV::loop; # the same thing
59			EV::loop EV::LOOP_ONCE; # block until some events could be handles
60			EV::loop EV::LOOP_NONBLOCK; # check and handle some events, but do not wait
61	root	1.2
62			DESCRIPTION
63			This module provides an interface to libevent
64			(<http://monkey.org/~provos/libevent/>). You probably should acquaint
65			yourself with its documentation and source code to be able to use this
66			module fully.
67
68			Please note thta this module disables the libevent EPOLL method by
69			default, see BUGS, below, if you need to enable it.
70
71	root	1.3	BASIC INTERFACE
72	root	1.2	$EV::NPRI
73			How many priority levels are available.
74
75	root	1.3	$EV::DIED
76			Must contain a reference to a function that is called when a
77			callback throws an exception (with $@ containing thr error). The
78			default prints an informative message and continues.
79
80			If this callback throws an exception it will be silently ignored.
81
82	root	1.2	$time = EV::now
83			Returns the time in (fractional) seconds since the epoch.
84
85			$version = EV::version
86			$method = EV::method
87			Return version string and event polling method used.
88
89			EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
90			EV::loopexit $after
91			Exit any active loop or dispatch after $after seconds or immediately
92			if $after is missing or zero.
93
94			EV::dispatch
95			Same as "EV::loop 0".
96
97			EV::event $callback
98			Creates a new event watcher waiting for nothing, calling the given
99			callback.
100
101			my $w = EV::io $fileno_or_fh, $eventmask, $callback
102			my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
103			As long as the returned watcher object is alive, call the $callback
104			when the events specified in $eventmask happen. Initially, the
105			timeout is disabled.
106
107	root	1.4	You can additionall set a timeout to occur on the watcher, but note
108	root	1.2	that this timeout will not be reset when you get an I/O event in the
109			EV::PERSIST case, and reaching a timeout will always stop the
110			watcher even in the EV::PERSIST case.
111
112			If you want a timeout to occur only after a specific time of
113			inactivity, set a repeating timeout and do NOT use EV::PERSIST.
114
115			Eventmask can be one or more of these constants ORed together:
116	root	1.1
117	root	1.2	EV::READ wait until read() wouldn't block anymore
118			EV::WRITE wait until write() wouldn't block anymore
119			EV::PERSIST stay active after a (non-timeout) event occured
120
121			The "io_ns" variant doesn't add/start the newly created watcher.
122
123	root	1.4	my $w = EV::timed_io $fileno_or_fh, $eventmask, $timeout, $callback
124			my $w = EV::timed_io_ns $fileno_or_fh, $eventmask, $timeout, $callback
125			Same as "io" and "io_ns", but also specifies a timeout (as if there
126			was a call to "$w->timeout ($timout, 1)". The persist flag is not
127			allowed and will automatically be cleared. The watcher will be
128			restarted after each event.
129
130			If the timeout is zero or undef, no timeout will be set, and a
131			normal watcher (with the persist flag set!) will be created.
132
133			This has the effect of timing out after the specified period of
134			inactivity has happened.
135
136			Due to the design of libevent, this is also relatively inefficient,
137			having one or two io watchers and a separate timeout watcher that
138			you reset on activity (by calling its "start" method) is usually
139			more efficient.
140
141	root	1.2	my $w = EV::timer $after, $repeat, $callback
142			my $w = EV::timer_ns $after, $repeat, $callback
143			Calls the callback after $after seconds. If $repeat is true, the
144			timer will be restarted after the callback returns. This means that
145			the callback would be called roughly every $after seconds, prolonged
146			by the time the callback takes.
147
148			The "timer_ns" variant doesn't add/start the newly created watcher.
149
150			my $w = EV::timer_abs $at, $interval, $callback
151			my $w = EV::timer_abs_ns $at, $interval, $callback
152			Similar to EV::timer, but the time is given as an absolute point in
153			time ($at), plus an optional $interval.
154
155			If the $interval is zero, then the callback will be called at the
156			time $at if that is in the future, or as soon as possible if its in
157			the past. It will not automatically repeat.
158
159			If the $interval is nonzero, then the watcher will always be
160			scheduled to time out at the next "$at + integer * $interval" time.
161
162			This can be used to schedule a callback to run at very regular
163			intervals, as long as the processing time is less then the interval
164			(otherwise obviously events will be skipped).
165
166			Another way to think about it (for the mathematically inclined) is
167			that "timer_abs" will try to tun the callback at the next possible
168			time where "$time = $at (mod $interval)", regardless of any time
169			jumps.
170
171			The "timer_abs_ns" variant doesn't add/start the newly created
172			watcher.
173
174	root	1.4	my $w = EV::signal $signal, $callback
175			my $w = EV::signal_ns $signal, $callback
176			Call the callback when $signal is received (the signal can be
177			specified by number or by name, just as with kill or %SIG). Signal
178			watchers are persistent no natter what.
179
180			EV will grab the signal for the process (the kernel only allows one
181			component to receive signals) when you start a signal watcher, and
182			removes it again when you stop it. Pelr does the same when you
183			add/remove callbacks to %SIG, so watch out.
184
185			Unfortunately, only one handler can be registered per signal. Screw
186			libevent.
187	root	1.2
188			The "signal_ns" variant doesn't add/start the newly created watcher.
189
190			THE EV::Event CLASS
191			All EV functions creating an event watcher (designated by "my $w ="
192			above) support the following methods on the returned watcher object:
193
194			$w->add ($timeout)
195			Stops and (re-)starts the event watcher, setting the optional
196			timeout to the given value, or clearing the timeout if none is
197			given.
198	root	1.1
199	root	1.2	$w->start
200			Stops and (re-)starts the event watcher without touching the
201			timeout.
202	root	1.1
203	root	1.2	$w->del
204			$w->stop
205			Stop the event watcher if it was started.
206	root	1.1
207	root	1.2	$current_callback = $w->cb
208			$old_callback = $w->cb ($new_callback)
209			Return the previously set callback and optionally set a new one.
210	root	1.1
211	root	1.2	$current_fh = $w->fh
212			$old_fh = $w->fh ($new_fh)
213	root	1.4	Returns the previously set filehandle and optionally set a new one
214			(also clears the EV::SIGNAL flag when setting a filehandle).
215
216			$current_signal = $w->signal
217			$old_signal = $w->signal ($new_signal)
218			Returns the previously set signal number and optionally set a new
219			one (also sets the EV::SIGNAL flag when setting a signal).
220	root	1.1
221	root	1.2	$current_eventmask = $w->events
222			$old_eventmask = $w->events ($new_eventmask)
223			Returns the previously set event mask and optionally set a new one.
224	root	1.1
225	root	1.2	$w->timeout ($after, $repeat)
226			Resets the timeout (see "EV::timer" for details).
227	root	1.1
228	root	1.2	$w->timeout_abs ($at, $interval)
229			Resets the timeout (see "EV::timer_abs" for details).
230	root	1.1
231	root	1.2	$w->priority_set ($priority)
232			Set the priority of the watcher to $priority (0 <= $priority <
233			$EV::NPRI).
234	root	1.1
235			BUGS
236	root	1.2	Lots. Libevent itself isn't well tested and rather buggy, and this
237			module is quite new at the moment.
238	root	1.1
239	root	1.2	Please note that the epoll method is not, in general, reliable in
240			programs that use fork (even if no libveent calls are being made in the
241			forked process). If your program behaves erratically, try setting the
242			environment variable "EVENT_NOEPOLL" first when running the program.
243
244			In general, if you fork, then you can only use the EV module in one of
245			the children.
246
247			SEE ALSO
248			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
249			L<EV::AnyEvent>.
250	root	1.1
251			AUTHOR
252			Marc Lehmann <schmorp@schmorp.de>
253			http://home.schmorp.de/
254