[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

     # IO

     my $w = EV::timer_abs 0, 60, sub {
        warn "is called every minute, on the minute, exactly";
     };

     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 "nothign received on stdin for 10 seconds, retrying";
        } else {
           warn "stdin is readable, you entered: ", <STDIN>;
        }
     };
     $w->timeout (10);

     # MAINLOOP
     EV::dispatch; # loop as long as watchers are active
     EV::loop;     # the same thing
     EV::loop EV::LOOP_ONCE;
     EV::loop EV::LOOP_ONSHOT;

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.

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

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

        Youc an 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::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 $signum, $callback
    my $w = EV::signal_ns $signum, $callback
        Call the callback when signal $signum is received.

        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.

    $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.2
Committed:	Sat Oct 27 19:11:27 2007 UTC (16 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.1:	+173 -894 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			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			# IO
20
21			my $w = EV::timer_abs 0, 60, sub {
22			warn "is called every minute, on the minute, exactly";
23			};
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 "nothign 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			# MAINLOOP
36			EV::dispatch; # loop as long as watchers are active
37			EV::loop; # the same thing
38			EV::loop EV::LOOP_ONCE;
39			EV::loop EV::LOOP_ONSHOT;
40
41			DESCRIPTION
42			This module provides an interface to libevent
43			(<http://monkey.org/~provos/libevent/>). You probably should acquaint
44			yourself with its documentation and source code to be able to use this
45			module fully.
46
47			Please note thta this module disables the libevent EPOLL method by
48			default, see BUGS, below, if you need to enable it.
49
50			FUNCTIONAL INTERFACE
51			$EV::NPRI
52			How many priority levels are available.
53
54			$time = EV::now
55			Returns the time in (fractional) seconds since the epoch.
56
57			$version = EV::version
58			$method = EV::method
59			Return version string and event polling method used.
60
61			EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
62			EV::loopexit $after
63			Exit any active loop or dispatch after $after seconds or immediately
64			if $after is missing or zero.
65
66			EV::dispatch
67			Same as "EV::loop 0".
68
69			EV::event $callback
70			Creates a new event watcher waiting for nothing, calling the given
71			callback.
72
73			my $w = EV::io $fileno_or_fh, $eventmask, $callback
74			my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
75			As long as the returned watcher object is alive, call the $callback
76			when the events specified in $eventmask happen. Initially, the
77			timeout is disabled.
78
79			Youc an additionall set a timeout to occur on the watcher, but note
80			that this timeout will not be reset when you get an I/O event in the
81			EV::PERSIST case, and reaching a timeout will always stop the
82			watcher even in the EV::PERSIST case.
83
84			If you want a timeout to occur only after a specific time of
85			inactivity, set a repeating timeout and do NOT use EV::PERSIST.
86
87			Eventmask can be one or more of these constants ORed together:
88	root	1.1
89	root	1.2	EV::READ wait until read() wouldn't block anymore
90			EV::WRITE wait until write() wouldn't block anymore
91			EV::PERSIST stay active after a (non-timeout) event occured
92
93			The "io_ns" variant doesn't add/start the newly created watcher.
94
95			my $w = EV::timer $after, $repeat, $callback
96			my $w = EV::timer_ns $after, $repeat, $callback
97			Calls the callback after $after seconds. If $repeat is true, the
98			timer will be restarted after the callback returns. This means that
99			the callback would be called roughly every $after seconds, prolonged
100			by the time the callback takes.
101
102			The "timer_ns" variant doesn't add/start the newly created watcher.
103
104			my $w = EV::timer_abs $at, $interval, $callback
105			my $w = EV::timer_abs_ns $at, $interval, $callback
106			Similar to EV::timer, but the time is given as an absolute point in
107			time ($at), plus an optional $interval.
108
109			If the $interval is zero, then the callback will be called at the
110			time $at if that is in the future, or as soon as possible if its in
111			the past. It will not automatically repeat.
112
113			If the $interval is nonzero, then the watcher will always be
114			scheduled to time out at the next "$at + integer * $interval" time.
115
116			This can be used to schedule a callback to run at very regular
117			intervals, as long as the processing time is less then the interval
118			(otherwise obviously events will be skipped).
119
120			Another way to think about it (for the mathematically inclined) is
121			that "timer_abs" will try to tun the callback at the next possible
122			time where "$time = $at (mod $interval)", regardless of any time
123			jumps.
124
125			The "timer_abs_ns" variant doesn't add/start the newly created
126			watcher.
127
128			my $w = EV::signal $signum, $callback
129			my $w = EV::signal_ns $signum, $callback
130			Call the callback when signal $signum is received.
131
132			The "signal_ns" variant doesn't add/start the newly created watcher.
133
134			THE EV::Event CLASS
135			All EV functions creating an event watcher (designated by "my $w ="
136			above) support the following methods on the returned watcher object:
137
138			$w->add ($timeout)
139			Stops and (re-)starts the event watcher, setting the optional
140			timeout to the given value, or clearing the timeout if none is
141			given.
142	root	1.1
143	root	1.2	$w->start
144			Stops and (re-)starts the event watcher without touching the
145			timeout.
146	root	1.1
147	root	1.2	$w->del
148			$w->stop
149			Stop the event watcher if it was started.
150	root	1.1
151	root	1.2	$current_callback = $w->cb
152			$old_callback = $w->cb ($new_callback)
153			Return the previously set callback and optionally set a new one.
154	root	1.1
155	root	1.2	$current_fh = $w->fh
156			$old_fh = $w->fh ($new_fh)
157			Returns the previously set filehandle and optionally set a new one.
158	root	1.1
159	root	1.2	$current_eventmask = $w->events
160			$old_eventmask = $w->events ($new_eventmask)
161			Returns the previously set event mask and optionally set a new one.
162	root	1.1
163	root	1.2	$w->timeout ($after, $repeat)
164			Resets the timeout (see "EV::timer" for details).
165	root	1.1
166	root	1.2	$w->timeout_abs ($at, $interval)
167			Resets the timeout (see "EV::timer_abs" for details).
168	root	1.1
169	root	1.2	$w->priority_set ($priority)
170			Set the priority of the watcher to $priority (0 <= $priority <
171			$EV::NPRI).
172	root	1.1
173			BUGS
174	root	1.2	Lots. Libevent itself isn't well tested and rather buggy, and this
175			module is quite new at the moment.
176	root	1.1
177	root	1.2	Please note that the epoll method is not, in general, reliable in
178			programs that use fork (even if no libveent calls are being made in the
179			forked process). If your program behaves erratically, try setting the
180			environment variable "EVENT_NOEPOLL" first when running the program.
181
182			In general, if you fork, then you can only use the EV module in one of
183			the children.
184
185			SEE ALSO
186			L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
187			L<EV::AnyEvent>.
188	root	1.1
189			AUTHOR
190			Marc Lehmann <schmorp@schmorp.de>
191			http://home.schmorp.de/
192