Coro/Event/Event.pm

=head1 NAME

Coro::Event - do events the coro-way, with Event

=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 Event qw(loop unloop); # we are re-exporting this, cooool!

use XSLoader;

use base Exporter::;

our @EXPORT = qw(loop unloop sweep);

BEGIN {
   our $VERSION = 5.12;

   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 $IDLE = new Coro sub {
   while () {
      &Event::one_event;
      &Coro::schedule;
   }
};
$IDLE->{desc} = "[Event idle process]";

$Coro::idle = $IDLE;

1;

=back

=head1 AUTHOR

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

=cut

Revision:	1.79
Committed:	Thu Dec 4 17:30:01 2008 UTC (15 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-5_12
Changes since 1.78:	+1 -1 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	Coro::Event - do events the coro-way, with Event
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	# 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	# use a separate coroutine for event processing, if impossible in main:
29	Coro::async { Event::loop };
30
31	=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	Coro::Event::loop.
44
45	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	=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	callbacks, you I<must never ever> call a Coroutine function that blocks
55	the current coroutine.
56
57	While this seems to work superficially, it will eventually cause memory
58	corruption and often results in deadlocks.
59
60	Best practise is to always use B<Coro::unblock_sub> for your callbacks.
61
62	=head1 SEMANTICS
63
64	Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.),
65	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	=head1 FUNCTIONS
75
76	=over 4
77
78	=cut
79
80	package Coro::Event;
81
82	no warnings;
83
84	use Carp;
85	no warnings;
86
87	use Coro;
88	use Event qw(loop unloop); # we are re-exporting this, cooool!
89
90	use XSLoader;
91
92	use base Exporter::;
93
94	our @EXPORT = qw(loop unloop sweep);
95
96	BEGIN {
97	our $VERSION = 5.12;
98
99	local $^W = 0; # avoid redefine warning for Coro::ready;
100	XSLoader::load __PACKAGE__, $VERSION;
101	}
102
103	=item $w = Coro::Event->flavour (args...)
104
105	Create and return a watcher of the given type.
106
107	Examples:
108
109	my $reader = Coro::Event->io (fd => $filehandle, poll => 'r');
110	$reader->next;
111
112	=cut
113
114	=item $w->next
115
116	Wait for and return the next event of the event queue of the watcher. The
117	returned event objects support two methods only: C<hits> and C<got>, both
118	of which return integers: the number this watcher was hit for this event,
119	and the mask of poll events received.
120
121	=cut
122
123	=item do_flavour args...
124
125	Create a watcher of the given type and immediately call it's next method,
126	returning the event.
127
128	This is less efficient then calling the constructor once and the next
129	method often, but it does save typing sometimes.
130
131	=cut
132
133	for my $flavour (qw(idle var timer io signal)) {
134	push @EXPORT, "do_$flavour";
135	my $new = \&{"Event::$flavour"};
136	my $class = "Coro::Event::$flavour";
137	my $type = $flavour eq "io" ? 1 : 0;
138	@{"${class}::ISA"} = (Coro::Event::, "Event::$flavour");
139	my $coronew = sub {
140	# how does one do method-call-by-name?
141	# my $w = $class->SUPER::$flavour(@_);
142
143	shift eq Coro::Event::
144	or croak "event constructor \"Coro::Event->$flavour\" must be called as a static method";
145
146	my $w = $new->($class,
147	desc => $flavour,
148	@_,
149	parked => 1,
150	);
151
152	_install_std_cb $w, $type;
153
154	# reblessing due to Event being broken
155	bless $w, $class
156	};
157	*{ $flavour } = $coronew;
158	*{"do_$flavour"} = sub {
159	unshift @_, Coro::Event::;
160	@_ = &$coronew;
161	&Coro::schedule while &_next;
162	$_[0]->cancel;
163	&_event
164	};
165	}
166
167	# do schedule in perl to avoid forcing a stack allocation.
168	# this is about 10% slower, though.
169	sub next($) {
170	&Coro::schedule while &_next;
171	&_event
172	}
173
174	sub Coro::Event::Event::hits { $_[0][3] }
175	sub Coro::Event::Event::got { $_[0][4] }
176
177	=item sweep
178
179	Similar to Event::one_event and Event::sweep: The idle task is called once
180	(this has the effect of jumping back into the Event loop once to serve new
181	events).
182
183	The reason this function exists is that you sometimes want to serve events
184	while doing other work. Calling C<Coro::cede> does not work because
185	C<cede> implies that the current coroutine is runnable and does not call
186	into the Event dispatcher.
187
188	=cut
189
190	sub sweep {
191	Event::one_event 0; # for now
192	}
193
194	=item $result = loop([$timeout])
195
196	This is the version of C<loop> you should use instead of C<Event::loop>
197	when using this module - it will ensure correct scheduling in the presence
198	of events.
199
200	=item unloop([$result])
201
202	Same as Event::unloop (provided here for your convinience only).
203
204	=cut
205
206	# very inefficient
207	our $IDLE = new Coro sub {
208	while () {
209	&Event::one_event;
210	&Coro::schedule;
211	}
212	};
213	$IDLE->{desc} = "[Event idle process]";
214
215	$Coro::idle = $IDLE;
216
217	1;
218
219	=back
220
221	=head1 AUTHOR
222
223	Marc Lehmann <schmorp@schmorp.de>
224	http://home.schmorp.de/
225
226	=cut
227