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.59 by root, Fri May 30 21:34:52 2008 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;
… …
19 } 19 }
20 20
21 loop; 21 loop;
22 22
23 # wait for input on stdin for one second 23 # wait for input on stdin for one second
24
25 Coro::Event::do_io (fd => \*STDIN, timeout => 1) & Event::Watcher::R 24 Coro::Event::do_io (fd => \*STDIN, timeout => 1) & Event::Watcher::R
26 or die "no input received"; 25 or die "no input received";
27 26
28 # use a separate coroutine for event processing, if impossible in main: 27 # use a separate thread for event processing, if impossible in main:
29 Coro::async { Event::loop }; 28 Coro::async { Event::loop };
30 29
31=head1 DESCRIPTION 30=head1 DESCRIPTION
32 31
33This module enables you to create programs using the powerful Event model 32This module enables you to create programs using the powerful Event model
… …
37This module provides a method and a function for every watcher type 36This module provides a method and a function for every watcher type
38(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
39watcher constructors from Event is that you do not specify a callback 38watcher constructors from Event is that you do not specify a callback
40function - it will be managed by this module. 39function - it will be managed by this module.
41 40
42Your application should just create all necessary coroutines and then call 41Your application should just create all necessary threads and then call
43Coro::Event::loop. 42C<Event::loop>.
44 43
45Please note that even programs or modules (such as 44Please note that even programs or modules (such as L<Coro::Handle>) that
46L<Coro::Handle|Coro::Handle>) that use "traditional"
47event-based/continuation style will run more efficient with this module 45use "traditional" event-based/continuation style will run more efficient
48then when using only Event. 46with this module then when using only Event.
49 47
50=head1 WARNING 48=head1 WARNING
51 49
52Please note that Event does not support coroutines or threads. That 50Please note that Event does not support multithreading. That means that
53means 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,
54callbacks, you I<must never ever> call a Coroutine function that blocks 52you I<must never ever> call a Coro function that blocks the current
55the current coroutine. 53thread.
56 54
57While this seems to work superficially, it will eventually cause memory 55While this seems to work superficially, it will eventually cause memory
58corruption and often results in deadlocks. 56corruption and often results in deadlocks.
59 57
60Best practise is to always use B<Coro::unblock_sub> for your callbacks. 58Best practise is to always use B<Coro::unblock_sub> for your callbacks.
61 59
62=head1 SEMANTICS 60=head1 SEMANTICS
63 61
64Whenever 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.),
65this 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
66priority. When any coroutines of lower priority are ready, it will not 64priority. When any threads of lower priority are ready, it will not
67block but run one of them and then check for events. 65block but run one of them and then check for events.
68 66
69The effect is that coroutines with the same or higher priority than 67The effect is that coroutines with the same or higher priority than
70the blocking coroutine will keep Event from checking for events, while 68the blocking coroutine will keep Event from checking for events, while
71coroutines with lower priority are being run, but Event checks for new 69coroutines with lower priority are being run, but Event checks for new
72events after every cede. 70events after every cede. Note that for this to work you actually need to
71run the event loop in some thread.
73 72
74=head1 FUNCTIONS 73=head1 FUNCTIONS
75 74
76=over 4 75=over 4
77 76
78=cut 77=cut
79 78
80package Coro::Event; 79package Coro::Event;
81 80
82no warnings; 81use common::sense;
83 82
84use Carp; 83use Carp;
85no warnings;
86 84
87use Coro; 85use Coro;
88use Event qw(loop unloop); # we are re-exporting this, cooool! 86use Event qw(loop unloop); # we are re-exporting this for historical reasons
89 87
90use XSLoader; 88use XSLoader;
91 89
92use base Exporter::; 90use base Exporter::;
93 91
94our @EXPORT = qw(loop unloop sweep); 92our @EXPORT = qw(loop unloop sweep);
95 93
96BEGIN { 94BEGIN {
97 our $VERSION = 4.741; 95 our $VERSION = 6.57;
98 96
99 local $^W = 0; # avoid redefine warning for Coro::ready; 97 local $^W = 0; # avoid redefine warning for Coro::ready;
100 XSLoader::load __PACKAGE__, $VERSION; 98 XSLoader::load __PACKAGE__, $VERSION;
101} 99}
102 100
… …
104 102
105Create and return a watcher of the given type. 103Create and return a watcher of the given type.
106 104
107Examples: 105Examples:
108 106
109 my $reader = Coro::Event->io(fd => $filehandle, poll => 'r'); 107 my $reader = Coro::Event->io (fd => $filehandle, poll => 'r');
110 $reader->next; 108 $reader->next;
111 109
112=cut 110=cut
113 111
114=item $w->next 112=item $w->next
… …
120 118
121=cut 119=cut
122 120
123=item do_flavour args... 121=item do_flavour args...
124 122
125Create a watcher of the given type and immediately call it's next method, 123Create a watcher of the given type and immediately call its next method,
126returning the event. 124returning the event.
127 125
128This is less efficient then calling the constructor once and the next 126This is less efficient then calling the constructor once and the next
129method often, but it does save typing sometimes. 127method often, but it does save typing sometimes.
130 128
… …
189 187
190sub sweep { 188sub sweep {
191 Event::one_event 0; # for now 189 Event::one_event 0; # for now
192} 190}
193 191
194=item $result = loop([$timeout])
195
196This is the version of C<loop> you should use instead of C<Event::loop>
197when using this module - it will ensure correct scheduling in the presence
198of events.
199
200=item unloop([$result])
201
202Same as Event::unloop (provided here for your convinience only).
203
204=cut
205
206# very inefficient 192# very inefficient
207our $event_idle = new Coro sub { 193our $IDLE = new Coro sub {
208 while () { 194 while () {
209 &Event::one_event; 195 Event::one_event;
210 &Coro::schedule; 196 Coro::schedule if Coro::nready;
211 } 197 }
212}; 198};
213$event_idle->{desc} = "[Event idle process]"; 199$IDLE->{desc} = "[Event idle thread]";
214 200
215$Coro::idle = sub { $event_idle->ready }; 201$Coro::idle = $IDLE;
216 202
2171; 2031;
218 204
219=back 205=back
220 206
221=head1 AUTHOR 207=head1 AUTHOR/SUPPORT/CONTACT
222 208
223 Marc Lehmann <schmorp@schmorp.de> 209 Marc A. Lehmann <schmorp@schmorp.de>
224 http://home.schmorp.de/ 210 http://software.schmorp.de/pkg/Coro.html
225 211
226=cut 212=cut
227 213

Diff Legend

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