Coro/Event/Event.pm

=head1 NAME

Coro::Event - do events the coro-way

=head1 SYNOPSIS

 use Coro;
 use Coro::Event;

 sub keyboard : Coro {
    my $w = Coro::Event->io(fd => \*STDIN, poll => 'r');
    while() {
       print "cmd> ";
       my $ev = $w->next; my $cmd = <STDIN>;
       unloop unless $cmd ne "";
       print "data> ";
       my $ev = $w->next; my $data = <STDIN>;
    }
 }

 loop;

 # wait for input on stdin for one second
 
 Coro::Event::do_io (fd => \*STDIN, timeout => 1) & Event::Watcher::R
    or die "no input received";

 # use a separate coroutine for event processing, if impossible in main:
 Coro::async { Event::loop };

=head1 DESCRIPTION

This module enables you to create programs using the powerful Event model
(and module), while retaining the linear style known from simple or
threaded programs.

This module provides a method and a function for every watcher type
(I<flavour>) (see L<Event>). The only difference between these and the
watcher constructors from Event is that you do not specify a callback
function - it will be managed by this module.

Your application should just create all necessary coroutines and then call
Coro::Event::loop.

Please note that even programs or modules (such as
L<Coro::Handle|Coro::Handle>) that use "traditional"
event-based/continuation style will run more efficient with this module
then when using only Event.

=head1 WARNING

Please note that Event does not support coroutines or threads. That
means that you B<MUST NOT> block in an event callback. Again: In Event
callbacks, you I<must never ever> call a Coroutine function that blocks
the current coroutine.

While this seems to work superficially, it will eventually cause memory
corruption and often results in deadlocks.

Best practise is to always use B<Coro::unblock_sub> for your callbacks.

=head1 SEMANTICS

Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.),
this module cede's to all other coroutines with the same or higher
priority. When any coroutines of lower priority are ready, it will not
block but run one of them and then check for events.

The effect is that coroutines with the same or higher priority than
the blocking coroutine will keep Event from checking for events, while
coroutines with lower priority are being run, but Event checks for new
events after every cede.

=head1 FUNCTIONS

=over 4

=cut

package Coro::Event;

no warnings;

use Carp;
no warnings;

use Coro;
use Coro::Timer;
use Event qw(loop unloop); # we are re-exporting this, cooool!

use XSLoader;

use base Exporter::;

our @EXPORT = qw(loop unloop sweep);

BEGIN {
   our $VERSION = '2.1';

   local $^W = 0; # avoid redefine warning for Coro::ready;
   XSLoader::load __PACKAGE__, $VERSION;
}

=item $w = Coro::Event->flavour (args...)

Create and return a watcher of the given type.

Examples:

  my $reader = Coro::Event->io(fd => $filehandle, poll => 'r');
  $reader->next;

=cut

=item $w->next

Wait for and return the next event of the event queue of the watcher. The
returned event objects support two methods only: C<hits> and C<got>, both
of which return integers: the number this watcher was hit for this event,
and the mask of poll events received.

=cut

=item do_flavour args...

Create a watcher of the given type and immediately call it's next method,
returning the event.

This is less efficient then calling the constructor once and the next
method often, but it does save typing sometimes.

=cut

for my $flavour (qw(idle var timer io signal)) {
   push @EXPORT, "do_$flavour";
   my $new = \&{"Event::$flavour"};
   my $class = "Coro::Event::$flavour";
   my $type = $flavour eq "io" ? 1 : 0;
   @{"${class}::ISA"} = (Coro::Event::, "Event::$flavour");
   my $coronew = sub {
      # how does one do method-call-by-name?
      # my $w = $class->SUPER::$flavour(@_);

      shift eq Coro::Event::
         or croak "event constructor \"Coro::Event->$flavour\" must be called as a static method";

      my $w = $new->($class,
         desc   => $flavour,
         @_,
         parked => 1,
      );

      _install_std_cb $w, $type;
      
      # reblessing due to Event being broken
      bless $w, $class
   };
   *{    $flavour } = $coronew;
   *{"do_$flavour"} = sub {
      unshift @_, Coro::Event::;
      @_ = &$coronew;
      &Coro::schedule while &_next;
      $_[0]->cancel;
      &_event
   };
}

# do schedule in perl to avoid forcing a stack allocation.
# this is about 10% slower, though.
sub next($) {
   &Coro::schedule while &_next;
   &_event
}

sub Coro::Event::Event::hits { $_[0][3] }
sub Coro::Event::Event::got  { $_[0][4] }

=item sweep

Similar to Event::one_event and Event::sweep: The idle task is called once
(this has the effect of jumping back into the Event loop once to serve new
events).

The reason this function exists is that you sometimes want to serve events
while doing other work. Calling C<Coro::cede> does not work because
C<cede> implies that the current coroutine is runnable and does not call
into the Event dispatcher.

=cut

sub sweep {
   Event::one_event 0; # for now
}

=item $result = loop([$timeout])

This is the version of C<loop> you should use instead of C<Event::loop>
when using this module - it will ensure correct scheduling in the presence
of events.

=item unloop([$result])

Same as Event::unloop (provided here for your convinience only).

=cut

# very inefficient
our $event_idle = new Coro sub {
   while () {
      &Event::one_event;
      &Coro::schedule;
   }
};
$event_idle->{desc} = "[Event idle process]";

$Coro::idle = sub { $event_idle->ready };

1;

=back

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.53
Committed:	Wed Oct 24 05:26:44 2007 UTC (16 years, 7 months ago) by root
Branch:	MAIN
CVS Tags:	rel-4_22, rel-4_21, rel-4_3, rel-4_13, rel-4_50, rel-4_51, rel-4_4, rel-4_45, rel-4_49, rel-4_48, rel-4_2, rel-4_47, rel-4_46, rel-4_31, rel-4_32, rel-4_33, rel-4_34, rel-4_35, rel-4_36, rel-4_37
Changes since 1.52:	+1 -0 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Coro::Event - do events the coro-way
4
5			=head1 SYNOPSIS
6
7			use Coro;
8			use Coro::Event;
9
10			sub keyboard : Coro {
11	pcg	1.21	my $w = Coro::Event->io(fd => \*STDIN, poll => 'r');
12	root	1.1	while() {
13			print "cmd> ";
14			my $ev = $w->next; my $cmd = <STDIN>;
15			unloop unless $cmd ne "";
16			print "data> ";
17			my $ev = $w->next; my $data = <STDIN>;
18			}
19			}
20
21	root	1.8	loop;
22	root	1.1
23	root	1.47	# wait for input on stdin for one second
24
25			Coro::Event::do_io (fd => \*STDIN, timeout => 1) & Event::Watcher::R
26			or die "no input received";
27
28	root	1.52	# use a separate coroutine for event processing, if impossible in main:
29			Coro::async { Event::loop };
30
31	root	1.1	=head1 DESCRIPTION
32
33			This module enables you to create programs using the powerful Event model
34			(and module), while retaining the linear style known from simple or
35			threaded programs.
36
37			This module provides a method and a function for every watcher type
38			(I<flavour>) (see L<Event>). The only difference between these and the
39			watcher constructors from Event is that you do not specify a callback
40			function - it will be managed by this module.
41
42			Your application should just create all necessary coroutines and then call
43	root	1.12	Coro::Event::loop.
44	root	1.1
45	root	1.37	Please note that even programs or modules (such as
46			L<Coro::Handle\|Coro::Handle>) that use "traditional"
47			event-based/continuation style will run more efficient with this module
48			then when using only Event.
49
50	root	1.42	=head1 WARNING
51
52			Please note that Event does not support coroutines or threads. That
53			means that you B<MUST NOT> block in an event callback. Again: In Event
54	root	1.52	callbacks, you I<must never ever> call a Coroutine function that blocks
55	root	1.42	the current coroutine.
56
57			While this seems to work superficially, it will eventually cause memory
58	root	1.52	corruption and often results in deadlocks.
59
60			Best practise is to always use B<Coro::unblock_sub> for your callbacks.
61	root	1.42
62	root	1.45	=head1 SEMANTICS
63
64	root	1.46	Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.),
65	root	1.45	this module cede's to all other coroutines with the same or higher
66			priority. When any coroutines of lower priority are ready, it will not
67			block but run one of them and then check for events.
68
69			The effect is that coroutines with the same or higher priority than
70			the blocking coroutine will keep Event from checking for events, while
71			coroutines with lower priority are being run, but Event checks for new
72			events after every cede.
73
74	root	1.42	=head1 FUNCTIONS
75
76	root	1.1	=over 4
77
78			=cut
79
80			package Coro::Event;
81
82	root	1.42	no warnings;
83	root	1.1
84			use Carp;
85	root	1.30	no warnings;
86	root	1.1
87			use Coro;
88	root	1.40	use Coro::Timer;
89	root	1.8	use Event qw(loop unloop); # we are re-exporting this, cooool!
90	root	1.1
91	root	1.30	use XSLoader;
92	root	1.1
93	root	1.30	use base Exporter::;
94
95	root	1.41	our @EXPORT = qw(loop unloop sweep);
96	root	1.1
97	root	1.2	BEGIN {
98	root	1.48	our $VERSION = '2.1';
99	root	1.2
100	root	1.13	local $^W = 0; # avoid redefine warning for Coro::ready;
101	root	1.30	XSLoader::load __PACKAGE__, $VERSION;
102	root	1.2	}
103	root	1.1
104	root	1.42	=item $w = Coro::Event->flavour (args...)
105	root	1.1
106			Create and return a watcher of the given type.
107
108			Examples:
109
110			my $reader = Coro::Event->io(fd => $filehandle, poll => 'r');
111			$reader->next;
112
113			=cut
114
115			=item $w->next
116
117	root	1.47	Wait for and return the next event of the event queue of the watcher. The
118			returned event objects support two methods only: C<hits> and C<got>, both
119			of which return integers: the number this watcher was hit for this event,
120			and the mask of poll events received.
121	root	1.1
122			=cut
123
124	root	1.42	=item do_flavour args...
125	root	1.1
126	root	1.47	Create a watcher of the given type and immediately call it's next method,
127			returning the event.
128
129			This is less efficient then calling the constructor once and the next
130			method often, but it does save typing sometimes.
131	root	1.1
132			=cut
133
134			for my $flavour (qw(idle var timer io signal)) {
135			push @EXPORT, "do_$flavour";
136			my $new = \&{"Event::$flavour"};
137			my $class = "Coro::Event::$flavour";
138	root	1.2	my $type = $flavour eq "io" ? 1 : 0;
139	root	1.1	@{"${class}::ISA"} = (Coro::Event::, "Event::$flavour");
140			my $coronew = sub {
141			# how does one do method-call-by-name?
142			# my $w = $class->SUPER::$flavour(@_);
143
144	root	1.10	shift eq Coro::Event::
145	root	1.1	or croak "event constructor \"Coro::Event->$flavour\" must be called as a static method";
146
147	root	1.10	my $w = $new->($class,
148	root	1.49	desc => $flavour,
149			@_,
150			parked => 1,
151	root	1.1	);
152	root	1.43
153			_install_std_cb $w, $type;
154
155			# reblessing due to Event being broken
156			bless $w, $class
157	root	1.1	};
158			*{ $flavour } = $coronew;
159			*{"do_$flavour"} = sub {
160			unshift @_, Coro::Event::;
161	root	1.50	@_ = &$coronew;
162			&Coro::schedule while &_next;
163	root	1.51	$_[0]->cancel;
164	root	1.50	&_event
165	root	1.1	};
166			}
167
168	root	1.50	# do schedule in perl to avoid forcing a stack allocation.
169			# this is about 10% slower, though.
170			sub next($) {
171			&Coro::schedule while &_next;
172			&_event
173			}
174
175	root	1.47	sub Coro::Event::Event::hits { $_[0][3] }
176			sub Coro::Event::Event::got { $_[0][4] }
177	root	1.1
178			=item sweep
179
180			Similar to Event::one_event and Event::sweep: The idle task is called once
181			(this has the effect of jumping back into the Event loop once to serve new
182			events).
183
184			The reason this function exists is that you sometimes want to serve events
185			while doing other work. Calling C<Coro::cede> does not work because
186			C<cede> implies that the current coroutine is runnable and does not call
187			into the Event dispatcher.
188
189			=cut
190
191			sub sweep {
192	root	1.42	Event::one_event 0; # for now
193	root	1.1	}
194
195			=item $result = loop([$timeout])
196
197			This is the version of C<loop> you should use instead of C<Event::loop>
198			when using this module - it will ensure correct scheduling in the presence
199			of events.
200
201			=item unloop([$result])
202
203			Same as Event::unloop (provided here for your convinience only).
204
205			=cut
206
207	root	1.52	# very inefficient
208			our $event_idle = new Coro sub {
209			while () {
210			&Event::one_event;
211			&Coro::schedule;
212			}
213			};
214	root	1.53	$event_idle->{desc} = "[Event idle process]";
215	root	1.52
216			$Coro::idle = sub { $event_idle->ready };
217	root	1.9
218	root	1.1	1;
219
220	root	1.36	=back
221
222	root	1.1	=head1 AUTHOR
223
224	root	1.27	Marc Lehmann <schmorp@schmorp.de>
225	root	1.25	http://home.schmorp.de/
226	root	1.1
227			=cut
228