ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
(Generate patch)

Comparing EV/EV.pm (file contents):
Revision 1.1 by root, Fri Oct 26 16:50:05 2007 UTC vs.
Revision 1.6 by root, Sat Oct 27 07:30:10 2007 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use EV; 7 use EV;
8 8
9 # TIMER
10
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 # IO
22
23 my $w = EV::timer_abs 0, 60, sub {
24 warn "is called every minute, on the minute, exactly";
25 };
26
27 my $w = EV::io \*STDIN, EV::READ | EV::PERSIST, sub {
28 my ($w, $events) = @_; # all callbacks get the watcher object and event mask
29 if ($events & EV::TIMEOUT) {
30 warn "nothign received on stdin for 10 seconds, retrying";
31 } else {
32 warn "stdin is readable, you entered: ", <STDIN>;
33 }
34 };
35 $w->timeout (10);
36
37 # MAINLOOP
38 EV::dispatch; # loop as long as watchers are active
39 EV::loop; # the same thing
40 EV::loop EV::LOOP_ONCE;
41 EV::loop EV::LOOP_ONSHOT;
42
9=head1 DESCRIPTION 43=head1 DESCRIPTION
10 44
11This module provides an interface to libevent 45This module provides an interface to libevent
12(L<http://monkey.org/~provos/libevent/>). 46(L<http://monkey.org/~provos/libevent/>). You probably should acquaint
47yourself with its documentation and source code to be able to use this
48module fully.
49
50Please note thta this module disables the libevent EPOLL method by
51default, see BUGS, below, if you need to enable it.
13 52
14=cut 53=cut
15 54
16package EV; 55package EV;
17 56
… …
25 64
26=head1 FUNCTIONAL INTERFACE 65=head1 FUNCTIONAL INTERFACE
27 66
28=over 4 67=over 4
29 68
69=item $EV::NPRI
70
71How many priority levels are available.
72
73=item $time = EV::now
74
75Returns the time in (fractional) seconds since the epoch.
76
77=item $version = EV::version
78
79=item $method = EV::method
80
81Return version string and event polling method used.
82
83=item EV::loop $flags # EV::LOOP_ONCE, EV::LOOP_ONESHOT
84
85=item EV::loopexit $after
86
87Exit any active loop or dispatch after C<$after> seconds or immediately if
88C<$after> is missing or zero.
89
90=item EV::dispatch
91
92Same as C<EV::loop 0>.
93
94=item EV::event $callback
95
96Creates a new event watcher waiting for nothing, calling the given callback.
97
98=item my $w = EV::io $fileno_or_fh, $eventmask, $callback
99
100=item my $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
101
102As long as the returned watcher object is alive, call the C<$callback>
103when the events specified in C<$eventmask> happen. Initially, the timeout
104is disabled.
105
106The C<io_ns> variant doesn't add/start the newly created watcher.
107
108Eventmask can be one or more of these constants ORed together:
109
110 EV::READ wait until read() wouldn't block anymore
111 EV::WRITE wait until write() wouldn't block anymore
112 EV::PERSIST stay active after an event occured
113
114=item my $w = EV::timer $after, $repeat, $callback
115
116=item my $w = EV::timer_ns $after, $repeat, $callback
117
118Calls the callback after C<$after> seconds. If C<$repeat> is true, the
119timer will be restarted after the callback returns. This means that the
120callback would be called roughly every C<$after> seconds, prolonged by the
121time the callback takes.
122
123The C<timer_ns> variant doesn't add/start the newly created watcher.
124
125=item my $w = EV::timer_abs $at, $interval, $callback
126
127=item my $w = EV::timer_abs_ns $at, $interval, $callback
128
129Similar to EV::timer, but the time is given as an absolute point in time
130(C<$at>), plus an optional C<$interval>.
131
132If the C<$interval> is zero, then the callback will be called at the time
133C<$at> if that is in the future, or as soon as possible if its in the
134past. It will not automatically repeat.
135
136If the C<$interval> is nonzero, then the watcher will always be scheduled
137to time out at the next C<$at + integer * $interval> time.
138
139This can be used to schedule a callback to run at very regular intervals,
140as long as the processing time is less then the interval (otherwise
141obviously events will be skipped).
142
143The C<timer_abs_ns> variant doesn't add/start the newly created watcher.
144
145=item my $w = EV::signal $signum, $callback
146
147=item my $w = EV::signal_ns $signum, $callback
148
149Call the callback when signal $signum is received.
150
151The C<signal_ns> variant doesn't add/start the newly created watcher.
152
30=back 153=back
31 154
155=head1 THE EV::Event CLASS
32 156
33=head1 OBJECT-ORIENTED INTERFACE 157All EV functions creating an event watcher (designated by C<my $w =>
34 158above) support the following methods on the returned watcher object:
35The object oriented interface lets you configure your own encoding or
36decoding style, within the limits of supported formats.
37 159
38=over 4 160=over 4
39 161
162=item $w->add ($timeout)
163
164Stops and (re-)starts the event watcher, setting the optional timeout to
165the given value, or clearing the timeout if none is given.
166
167=item $w->start
168
169Stops and (re-)starts the event watcher without touching the timeout.
170
171=item $w->del
172
173=item $w->stop
174
175Stop the event watcher if it was started.
176
177=item $current_callback = $w->cb
178
179=item $old_callback = $w->cb ($new_callback)
180
181Return the previously set callback and optionally set a new one.
182
183=item $current_fh = $w->fh
184
185=item $old_fh = $w->fh ($new_fh)
186
187Returns the previously set filehandle and optionally set a new one.
188
189=item $current_eventmask = $w->events
190
191=item $old_eventmask = $w->events ($new_eventmask)
192
193Returns the previously set event mask and optionally set a new one.
194
195=item $w->timeout ($after, $repeat)
196
197Resets the timeout (see C<EV::timer> for details).
198
199=item $w->timeout_abs ($at, $interval)
200
201Resets the timeout (see C<EV::timer_abs> for details).
202
203=item $w->priority_set ($priority)
204
205Set the priority of the watcher to C<$priority> (0 <= $priority < $EV::NPRI).
206
40=back 207=back
41 208
42=head1 BUGS 209=head1 BUGS
43 210
211Lots. Libevent itself isn't well tested and rather buggy, and this module
212is quite new at the moment.
213
214Please note that the epoll method is not, in general, reliable in
215programs that use fork (even if no libveent calls are being made in the
216forked process). Since this is such a common issue, this module will
217force the epoll method in EV to be off *unless* the global variable
218$EV::ENABLE_EPOLL is set to 1 *before* loading this module for the first
219time.
220
44=cut 221=cut
45 222
46our $NPRI = 4; 223our $NPRI = 4;
224our $BASE;
225our $ENABLE_EPOLL;
226
227{
228 local $ENV{EVENT_NOEPOLL};
229 $ENV{EVENT_NOEPOLL} = 1 unless $ENABLE_EPOLL;
47our $BASE = init; 230 $BASE = init;
231}
232
48priority_init $NPRI; 233priority_init $NPRI;
49 234
235push @AnyEvent::REGISTRY, [EV => "EV::AnyEvent"];
236
501; 2371;
238
239=head1 SEE ALSO
240
241 L<EV::DNS>, L<event(3)>, L<event.h>, L<evdns.h>.
242 L<EV::AnyEvent>.
51 243
52=head1 AUTHOR 244=head1 AUTHOR
53 245
54 Marc Lehmann <schmorp@schmorp.de> 246 Marc Lehmann <schmorp@schmorp.de>
55 http://home.schmorp.de/ 247 http://home.schmorp.de/

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines