File Coverage

blib/lib/Mojo/Reactor.pm
Criterion Covered Total %
statement 27 27 100.0
branch 3 4 75.0
condition 4 6 66.6
subroutine 17 17 100.0
pod 13 13 100.0
total 64 67 95.5


line stmt bran cond sub pod time code
1             package Mojo::Reactor;
2 64     64   510 use Mojo::Base 'Mojo::EventEmitter';
  64         145  
  64         564  
3              
4 64     64   494 use Carp qw(croak);
  64         178  
  64         3378  
5 64     64   444 use Config;
  64         244  
  64         3348  
6 64     64   22710 use Mojo::Loader qw(load_class);
  64         202  
  64         31031  
7              
8             my %DETECTED;
9              
10 1     1 1 119 sub again { croak 'Method "again" not implemented by subclass' }
11              
12             sub detect {
13 97 50   97 1 10056 my $default = 'Mojo::Reactor::' . ($Config{d_pseudofork} ? 'Poll' : 'EV');
14 97   66     812 my $try = $ENV{MOJO_REACTOR} || $default;
15 97 100 66     796 return $DETECTED{$try} ||= load_class($try) ? 'Mojo::Reactor::Poll' : $try;
16             }
17              
18 1     1 1 709 sub io { croak 'Method "io" not implemented by subclass' }
19 1     1 1 692 sub is_running { croak 'Method "is_running" not implemented by subclass' }
20 1     1 1 717 sub next_tick { croak 'Method "next_tick" not implemented by subclass' }
21 1     1 1 754 sub one_tick { croak 'Method "one_tick" not implemented by subclass' }
22 1     1 1 752 sub recurring { croak 'Method "recurring" not implemented by subclass' }
23 1     1 1 702 sub remove { croak 'Method "remove" not implemented by subclass' }
24 1     1 1 686 sub reset { croak 'Method "reset" not implemented by subclass' }
25 1     1 1 681 sub start { croak 'Method "start" not implemented by subclass' }
26 1     1 1 700 sub stop { croak 'Method "stop" not implemented by subclass' }
27 1     1 1 797 sub timer { croak 'Method "timer" not implemented by subclass' }
28 1     1 1 745 sub watch { croak 'Method "watch" not implemented by subclass' }
29              
30             1;
31              
32             =encoding utf8
33              
34             =head1 NAME
35              
36             Mojo::Reactor - Low-level event reactor base class
37              
38             =head1 SYNOPSIS
39              
40             package Mojo::Reactor::MyEventLoop;
41             use Mojo::Base 'Mojo::Reactor';
42              
43             sub again {...}
44             sub io {...}
45             sub is_running {...}
46             sub next_tick {...}
47             sub one_tick {...}
48             sub recurring {...}
49             sub remove {...}
50             sub reset {...}
51             sub start {...}
52             sub stop {...}
53             sub timer {...}
54             sub watch {...}
55              
56             =head1 DESCRIPTION
57              
58             L is an abstract base class for low-level event reactors, like L and
59             L.
60              
61             =head1 EVENTS
62              
63             L inherits all events from L and can emit the following new ones.
64              
65             =head2 error
66              
67             $reactor->on(error => sub ($reactor, $err) {...});
68              
69             Emitted for exceptions caught in callbacks, fatal if unhandled. Note that if this event is unhandled or fails it might
70             kill your program, so you need to be careful.
71              
72             $reactor->on(error => sub ($reactor, $err) { say "Something very bad happened: $err" });
73              
74             =head1 METHODS
75              
76             L inherits all methods from L and implements the following new ones.
77              
78             =head2 again
79              
80             $reactor->again($id);
81             $reactor->again($id, 0.5);
82              
83             Restart timer and optionally change the invocation time. Meant to be overloaded in a subclass. Note that this method
84             requires an active timer.
85              
86             =head2 detect
87              
88             my $class = Mojo::Reactor->detect;
89              
90             Detect and load the best reactor implementation available, will try the value of the C environment
91             variable, L or L.
92              
93             # Instantiate best reactor implementation available
94             my $reactor = Mojo::Reactor->detect->new;
95              
96             =head2 io
97              
98             $reactor = $reactor->io($handle => sub {...});
99              
100             Watch handle for I/O events, invoking the callback whenever handle becomes readable or writable. Meant to be overloaded
101             in a subclass.
102              
103             # Callback will be executed twice if handle becomes readable and writable
104             $reactor->io($handle => sub ($reactor, $writable) {
105             say $writable ? 'Handle is writable' : 'Handle is readable';
106             });
107              
108             =head2 is_running
109              
110             my $bool = $reactor->is_running;
111              
112             Check if reactor is running. Meant to be overloaded in a subclass.
113              
114             =head2 next_tick
115              
116             my $undef = $reactor->next_tick(sub {...});
117              
118             Execute callback as soon as possible, but not before returning or other callbacks that have been registered with this
119             method, always returns C. Meant to be overloaded in a subclass.
120              
121             =head2 one_tick
122              
123             $reactor->one_tick;
124              
125             Run reactor until an event occurs. Note that this method can recurse back into the reactor, so you need to be careful.
126             Meant to be overloaded in a subclass.
127              
128             # Don't block longer than 0.5 seconds
129             my $id = $reactor->timer(0.5 => sub {});
130             $reactor->one_tick;
131             $reactor->remove($id);
132              
133             =head2 recurring
134              
135             my $id = $reactor->recurring(0.25 => sub {...});
136              
137             Create a new recurring timer, invoking the callback repeatedly after a given amount of time in seconds. Meant to be
138             overloaded in a subclass.
139              
140             =head2 remove
141              
142             my $bool = $reactor->remove($handle);
143             my $bool = $reactor->remove($id);
144              
145             Remove handle or timer. Meant to be overloaded in a subclass.
146              
147             =head2 reset
148              
149             $reactor->reset;
150              
151             Remove all handles and timers. Meant to be overloaded in a subclass.
152              
153             =head2 start
154              
155             $reactor->start;
156              
157             Start watching for I/O and timer events, this will block until L is called. Note that some reactors stop
158             automatically if there are no events being watched anymore. Meant to be overloaded in a subclass.
159              
160             # Start reactor only if it is not running already
161             $reactor->start unless $reactor->is_running;
162              
163             =head2 stop
164              
165             $reactor->stop;
166              
167             Stop watching for I/O and timer events. Meant to be overloaded in a subclass.
168              
169             =head2 timer
170              
171             my $id = $reactor->timer(0.5 => sub {...});
172              
173             Create a new timer, invoking the callback after a given amount of time in seconds. Meant to be overloaded in a
174             subclass.
175              
176             =head2 watch
177              
178             $reactor = $reactor->watch($handle, $readable, $writable);
179              
180             Change I/O events to watch handle for with true and false values. Meant to be overloaded in a subclass. Note that this
181             method requires an active I/O watcher.
182              
183             # Watch only for readable events
184             $reactor->watch($handle, 1, 0);
185              
186             # Watch only for writable events
187             $reactor->watch($handle, 0, 1);
188              
189             # Watch for readable and writable events
190             $reactor->watch($handle, 1, 1);
191              
192             # Pause watching for events
193             $reactor->watch($handle, 0, 0);
194              
195             =head1 SEE ALSO
196              
197             L, L, L.
198              
199             =cut