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

Comparing Coro/Event/Event.pm (file contents):
Revision 1.46 by root, Fri Dec 29 12:05:55 2006 UTC vs.
Revision 1.147 by root, Mon Mar 16 11:12:53 2020 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro::Event - do events the coro-way 3Coro::Event - do events the coro-way, with Event
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Coro; 7 use Coro;
8 use Coro::Event; 8 use Coro::Event;
… …
18 } 18 }
19 } 19 }
20 20
21 loop; 21 loop;
22 22
23 # wait for input on stdin for one second
24 Coro::Event::do_io (fd => \*STDIN, timeout => 1) & Event::Watcher::R
25 or die "no input received";
26
27 # use a separate thread for event processing, if impossible in main:
28 Coro::async { Event::loop };
29
23=head1 DESCRIPTION 30=head1 DESCRIPTION
24 31
25This module enables you to create programs using the powerful Event model 32This module enables you to create programs using the powerful Event model
26(and module), while retaining the linear style known from simple or 33(and module), while retaining the linear style known from simple or
27threaded programs. 34threaded programs.
… …
29This module provides a method and a function for every watcher type 36This module provides a method and a function for every watcher type
30(I<flavour>) (see L<Event>). The only difference between these and the 37(I<flavour>) (see L<Event>). The only difference between these and the
31watcher constructors from Event is that you do not specify a callback 38watcher constructors from Event is that you do not specify a callback
32function - it will be managed by this module. 39function - it will be managed by this module.
33 40
34Your application should just create all necessary coroutines and then call 41Your application should just create all necessary threads and then call
35Coro::Event::loop. 42C<Event::loop>.
36 43
37Please note that even programs or modules (such as 44Please note that even programs or modules (such as L<Coro::Handle>) that
38L<Coro::Handle|Coro::Handle>) that use "traditional"
39event-based/continuation style will run more efficient with this module 45use "traditional" event-based/continuation style will run more efficient
40then when using only Event. 46with this module then when using only Event.
41 47
42=head1 WARNING 48=head1 WARNING
43 49
44Please note that Event does not support coroutines or threads. That 50Please note that Event does not support multithreading. That means that
45means that you B<MUST NOT> block in an event callback. Again: In Event 51you B<MUST NOT> block in an event callback. Again: In Event callbacks,
46callbacks, you I<must never ever> call a Coroutine fucntion that blocks 52you I<must never ever> call a Coro function that blocks the current
47the current coroutine. 53thread.
48 54
49While this seems to work superficially, it will eventually cause memory 55While this seems to work superficially, it will eventually cause memory
50corruption. 56corruption and often results in deadlocks.
57
58Best practise is to always use B<Coro::unblock_sub> for your callbacks.
51 59
52=head1 SEMANTICS 60=head1 SEMANTICS
53 61
54Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.), 62Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.),
55this module cede's to all other coroutines with the same or higher 63this module cede's to all other threads with the same or higher
56priority. When any coroutines of lower priority are ready, it will not 64priority. When any threads of lower priority are ready, it will not
57block but run one of them and then check for events. 65block but run one of them and then check for events.
58 66
59The effect is that coroutines with the same or higher priority than 67The effect is that coroutines with the same or higher priority than
60the blocking coroutine will keep Event from checking for events, while 68the blocking coroutine will keep Event from checking for events, while
61coroutines with lower priority are being run, but Event checks for new 69coroutines with lower priority are being run, but Event checks for new
62events after every cede. 70events after every cede. Note that for this to work you actually need to
71run the event loop in some thread.
63 72
64=head1 FUNCTIONS 73=head1 FUNCTIONS
65 74
66=over 4 75=over 4
67 76
68=cut 77=cut
69 78
70package Coro::Event; 79package Coro::Event;
71 80
72no warnings; 81use common::sense;
73 82
74use Carp; 83use Carp;
75no warnings;
76 84
77use Coro; 85use Coro;
78use Coro::Timer;
79use Event qw(loop unloop); # we are re-exporting this, cooool! 86use Event qw(loop unloop); # we are re-exporting this for historical reasons
80 87
81use XSLoader; 88use XSLoader;
82 89
83use base Exporter::; 90use base Exporter::;
84 91
85our @EXPORT = qw(loop unloop sweep); 92our @EXPORT = qw(loop unloop sweep);
86 93
87BEGIN { 94BEGIN {
88 our $VERSION = '2.0'; 95 our $VERSION = 6.57;
89 96
90 local $^W = 0; # avoid redefine warning for Coro::ready; 97 local $^W = 0; # avoid redefine warning for Coro::ready;
91 XSLoader::load __PACKAGE__, $VERSION; 98 XSLoader::load __PACKAGE__, $VERSION;
92} 99}
93 100
… …
95 102
96Create and return a watcher of the given type. 103Create and return a watcher of the given type.
97 104
98Examples: 105Examples:
99 106
100 my $reader = Coro::Event->io(fd => $filehandle, poll => 'r'); 107 my $reader = Coro::Event->io (fd => $filehandle, poll => 'r');
101 $reader->next; 108 $reader->next;
102 109
103=cut 110=cut
104 111
105=item $w->next 112=item $w->next
106 113
107Return the next event of the event queue of the watcher. 114Wait for and return the next event of the event queue of the watcher. The
115returned event objects support two methods only: C<hits> and C<got>, both
116of which return integers: the number this watcher was hit for this event,
117and the mask of poll events received.
108 118
109=cut 119=cut
110 120
111=item do_flavour args... 121=item do_flavour args...
112 122
113Create a watcher of the given type and immediately call it's next 123Create a watcher of the given type and immediately call its next method,
124returning the event.
125
114method. This is less efficient then calling the constructor once and the 126This is less efficient then calling the constructor once and the next
115next method often, but it does save typing sometimes. 127method often, but it does save typing sometimes.
116 128
117=cut 129=cut
118 130
119for my $flavour (qw(idle var timer io signal)) { 131for my $flavour (qw(idle var timer io signal)) {
120 push @EXPORT, "do_$flavour"; 132 push @EXPORT, "do_$flavour";
… …
128 140
129 shift eq Coro::Event:: 141 shift eq Coro::Event::
130 or croak "event constructor \"Coro::Event->$flavour\" must be called as a static method"; 142 or croak "event constructor \"Coro::Event->$flavour\" must be called as a static method";
131 143
132 my $w = $new->($class, 144 my $w = $new->($class,
133 desc => $flavour, 145 desc => $flavour,
134 @_, 146 @_,
135 parked => 1, 147 parked => 1,
136 ); 148 );
137 149
138 _install_std_cb $w, $type; 150 _install_std_cb $w, $type;
139 151
140 # reblessing due to Event being broken 152 # reblessing due to Event being broken
… …
152 164
153# do schedule in perl to avoid forcing a stack allocation. 165# do schedule in perl to avoid forcing a stack allocation.
154# this is about 10% slower, though. 166# this is about 10% slower, though.
155sub next($) { 167sub next($) {
156 &Coro::schedule while &_next; 168 &Coro::schedule while &_next;
157
158 &_event 169 &_event
159} 170}
160 171
172sub Coro::Event::Event::hits { $_[0][3] }
161sub Coro::Event::w { $_[0] } 173sub Coro::Event::Event::got { $_[0][4] }
162sub Coro::Event::prio { $_[0]{Coro::Event}[3] }
163sub Coro::Event::hits { $_[0]{Coro::Event}[4] }
164sub Coro::Event::got { $_[0]{Coro::Event}[5] }
165 174
166=item sweep 175=item sweep
167 176
168Similar to Event::one_event and Event::sweep: The idle task is called once 177Similar to Event::one_event and Event::sweep: The idle task is called once
169(this has the effect of jumping back into the Event loop once to serve new 178(this has the effect of jumping back into the Event loop once to serve new
… …
178 187
179sub sweep { 188sub sweep {
180 Event::one_event 0; # for now 189 Event::one_event 0; # for now
181} 190}
182 191
183=item $result = loop([$timeout]) 192# very inefficient
193our $IDLE = new Coro sub {
194 while () {
195 Event::one_event;
196 Coro::schedule if Coro::nready;
197 }
198};
199$IDLE->{desc} = "[Event idle thread]";
184 200
185This is the version of C<loop> you should use instead of C<Event::loop> 201$Coro::idle = $IDLE;
186when using this module - it will ensure correct scheduling in the presence
187of events.
188
189=item unloop([$result])
190
191Same as Event::unloop (provided here for your convinience only).
192
193=cut
194
195$Coro::idle = \&Event::one_event; # inefficient
196 202
1971; 2031;
198 204
199=back 205=back
200 206
201=head1 AUTHOR 207=head1 AUTHOR/SUPPORT/CONTACT
202 208
203 Marc Lehmann <schmorp@schmorp.de> 209 Marc A. Lehmann <schmorp@schmorp.de>
204 http://home.schmorp.de/ 210 http://software.schmorp.de/pkg/Coro.html
205 211
206=cut 212=cut
207 213

Diff Legend

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