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;

=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 fucntion that blocks
the current coroutine.

While this seems to work superficially, it will eventually cause memory
corruption.

=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.0';

   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

Return the next event of the event queue of the watcher.

=cut

=item do_flavour args...

Create a watcher of the given type and immediately call it's next
method. 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::w    { $_[0] }
sub Coro::Event::prio { $_[0]{Coro::Event}[3] }
sub Coro::Event::hits { $_[0]{Coro::Event}[4] }
sub Coro::Event::got  { $_[0]{Coro::Event}[5] }

=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

$Coro::idle = \&Event::one_event; # inefficient

1;

=back

=head1 AUTHOR

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

=cut

Revision:	1.46
Committed:	Fri Dec 29 12:05:55 2006 UTC (17 years, 5 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_41, rel-3_4, rel-3_3
Changes since 1.45:	+2 -2 lines
Log Message:	* empty log message *
#	Content
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	my $w = Coro::Event->io(fd => \*STDIN, poll => 'r');
12	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	loop;
22
23	=head1 DESCRIPTION
24
25	This module enables you to create programs using the powerful Event model
26	(and module), while retaining the linear style known from simple or
27	threaded programs.
28
29	This module provides a method and a function for every watcher type
30	(I<flavour>) (see L<Event>). The only difference between these and the
31	watcher constructors from Event is that you do not specify a callback
32	function - it will be managed by this module.
33
34	Your application should just create all necessary coroutines and then call
35	Coro::Event::loop.
36
37	Please note that even programs or modules (such as
38	L<Coro::Handle\|Coro::Handle>) that use "traditional"
39	event-based/continuation style will run more efficient with this module
40	then when using only Event.
41
42	=head1 WARNING
43
44	Please note that Event does not support coroutines or threads. That
45	means that you B<MUST NOT> block in an event callback. Again: In Event
46	callbacks, you I<must never ever> call a Coroutine fucntion that blocks
47	the current coroutine.
48
49	While this seems to work superficially, it will eventually cause memory
50	corruption.
51
52	=head1 SEMANTICS
53
54	Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.),
55	this module cede's to all other coroutines with the same or higher
56	priority. When any coroutines of lower priority are ready, it will not
57	block but run one of them and then check for events.
58
59	The effect is that coroutines with the same or higher priority than
60	the blocking coroutine will keep Event from checking for events, while
61	coroutines with lower priority are being run, but Event checks for new
62	events after every cede.
63
64	=head1 FUNCTIONS
65
66	=over 4
67
68	=cut
69
70	package Coro::Event;
71
72	no warnings;
73
74	use Carp;
75	no warnings;
76
77	use Coro;
78	use Coro::Timer;
79	use Event qw(loop unloop); # we are re-exporting this, cooool!
80
81	use XSLoader;
82
83	use base Exporter::;
84
85	our @EXPORT = qw(loop unloop sweep);
86
87	BEGIN {
88	our $VERSION = '2.0';
89
90	local $^W = 0; # avoid redefine warning for Coro::ready;
91	XSLoader::load __PACKAGE__, $VERSION;
92	}
93
94	=item $w = Coro::Event->flavour (args...)
95
96	Create and return a watcher of the given type.
97
98	Examples:
99
100	my $reader = Coro::Event->io(fd => $filehandle, poll => 'r');
101	$reader->next;
102
103	=cut
104
105	=item $w->next
106
107	Return the next event of the event queue of the watcher.
108
109	=cut
110
111	=item do_flavour args...
112
113	Create a watcher of the given type and immediately call it's next
114	method. This is less efficient then calling the constructor once and the
115	next method often, but it does save typing sometimes.
116
117	=cut
118
119	for my $flavour (qw(idle var timer io signal)) {
120	push @EXPORT, "do_$flavour";
121	my $new = \&{"Event::$flavour"};
122	my $class = "Coro::Event::$flavour";
123	my $type = $flavour eq "io" ? 1 : 0;
124	@{"${class}::ISA"} = (Coro::Event::, "Event::$flavour");
125	my $coronew = sub {
126	# how does one do method-call-by-name?
127	# my $w = $class->SUPER::$flavour(@_);
128
129	shift eq Coro::Event::
130	or croak "event constructor \"Coro::Event->$flavour\" must be called as a static method";
131
132	my $w = $new->($class,
133	desc => $flavour,
134	@_,
135	parked => 1,
136	);
137
138	_install_std_cb $w, $type;
139
140	# reblessing due to Event being broken
141	bless $w, $class
142	};
143	*{ $flavour } = $coronew;
144	*{"do_$flavour"} = sub {
145	unshift @_, Coro::Event::;
146	@_ = &$coronew;
147	&Coro::schedule while &_next;
148	$_[0]->cancel;
149	&_event
150	};
151	}
152
153	# do schedule in perl to avoid forcing a stack allocation.
154	# this is about 10% slower, though.
155	sub next($) {
156	&Coro::schedule while &_next;
157
158	&_event
159	}
160
161	sub Coro::Event::w { $_[0] }
162	sub Coro::Event::prio { $_[0]{Coro::Event}[3] }
163	sub Coro::Event::hits { $_[0]{Coro::Event}[4] }
164	sub Coro::Event::got { $_[0]{Coro::Event}[5] }
165
166	=item sweep
167
168	Similar 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
170	events).
171
172	The reason this function exists is that you sometimes want to serve events
173	while doing other work. Calling C<Coro::cede> does not work because
174	C<cede> implies that the current coroutine is runnable and does not call
175	into the Event dispatcher.
176
177	=cut
178
179	sub sweep {
180	Event::one_event 0; # for now
181	}
182
183	=item $result = loop([$timeout])
184
185	This is the version of C<loop> you should use instead of C<Event::loop>
186	when using this module - it will ensure correct scheduling in the presence
187	of events.
188
189	=item unloop([$result])
190
191	Same as Event::unloop (provided here for your convinience only).
192
193	=cut
194
195	$Coro::idle = \&Event::one_event; # inefficient
196
197	1;
198
199	=back
200
201	=head1 AUTHOR
202
203	Marc Lehmann <schmorp@schmorp.de>
204	http://home.schmorp.de/
205
206	=cut
207