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.

=over 4

=cut

package Coro::Event;

BEGIN { eval { require warnings } && warnings->unimport ("uninitialized") }

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 reschedule);

BEGIN {
   our $VERSION = 1.9;

   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);
      bless $w, $class; # reblessing due to broken Event
   };
   *{    $flavour } = $coronew;
   *{"do_$flavour"} = sub {
      unshift @_, Coro::Event::;
      my $e = (&$coronew)->next;
      $e->cancel; # $e === $e->w
      $e;
   };
}

# double calls to avoid stack-cloning ;()
# is about 10% slower, though.
sub next($) {
   &Coro::schedule if &_next; $_[0];
}

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.40
Committed:	Fri Nov 24 15:34:33 2006 UTC (17 years, 7 months ago) by root
Branch:	MAIN
CVS Tags:	stack_sharing
Changes since 1.39:	+2 -17 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			=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	root	1.12	Coro::Event::loop.
36	root	1.1
37	root	1.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	root	1.1	=over 4
43
44			=cut
45
46			package Coro::Event;
47
48	pcg	1.18	BEGIN { eval { require warnings } && warnings->unimport ("uninitialized") }
49	root	1.1
50			use Carp;
51	root	1.30	no warnings;
52	root	1.1
53			use Coro;
54	root	1.40	use Coro::Timer;
55	root	1.8	use Event qw(loop unloop); # we are re-exporting this, cooool!
56	root	1.1
57	root	1.30	use XSLoader;
58	root	1.1
59	root	1.30	use base Exporter::;
60
61			our @EXPORT = qw(loop unloop sweep reschedule);
62	root	1.1
63	root	1.2	BEGIN {
64	root	1.35	our $VERSION = 1.9;
65	root	1.2
66	root	1.13	local $^W = 0; # avoid redefine warning for Coro::ready;
67	root	1.30	XSLoader::load __PACKAGE__, $VERSION;
68	root	1.2	}
69	root	1.1
70			=item $w = Coro::Event->flavour(args...)
71
72			Create and return a watcher of the given type.
73
74			Examples:
75
76			my $reader = Coro::Event->io(fd => $filehandle, poll => 'r');
77			$reader->next;
78
79			=cut
80
81			=item $w->next
82
83			Return the next event of the event queue of the watcher.
84
85			=cut
86
87			=item do_flavour(args...)
88
89			Create a watcher of the given type and immediately call it's next
90			method. This is less efficient then calling the constructor once and the
91			next method often, but it does save typing sometimes.
92
93			=cut
94
95			for my $flavour (qw(idle var timer io signal)) {
96			push @EXPORT, "do_$flavour";
97			my $new = \&{"Event::$flavour"};
98			my $class = "Coro::Event::$flavour";
99	root	1.2	my $type = $flavour eq "io" ? 1 : 0;
100	root	1.1	@{"${class}::ISA"} = (Coro::Event::, "Event::$flavour");
101			my $coronew = sub {
102			# how does one do method-call-by-name?
103			# my $w = $class->SUPER::$flavour(@_);
104
105	root	1.10	shift eq Coro::Event::
106	root	1.1	or croak "event constructor \"Coro::Event->$flavour\" must be called as a static method";
107
108	root	1.10	my $w = $new->($class,
109	root	1.1	desc => $flavour,
110			@_,
111	root	1.2	parked => 1,
112	root	1.1	);
113	root	1.2	_install_std_cb($w, $type);
114	root	1.1	bless $w, $class; # reblessing due to broken Event
115			};
116			*{ $flavour } = $coronew;
117			*{"do_$flavour"} = sub {
118			unshift @_, Coro::Event::;
119			my $e = (&$coronew)->next;
120	pcg	1.20	$e->cancel; # $e === $e->w
121	root	1.1	$e;
122			};
123			}
124
125	root	1.2	# double calls to avoid stack-cloning ;()
126	root	1.3	# is about 10% slower, though.
127	root	1.2	sub next($) {
128	root	1.3	&Coro::schedule if &_next; $_[0];
129	root	1.1	}
130	root	1.2
131	root	1.4	sub Coro::Event::w { $_[0] }
132	root	1.5	sub Coro::Event::prio { $_[0]{Coro::Event}[3] }
133			sub Coro::Event::hits { $_[0]{Coro::Event}[4] }
134			sub Coro::Event::got { $_[0]{Coro::Event}[5] }
135	root	1.1
136			=item sweep
137
138			Similar to Event::one_event and Event::sweep: The idle task is called once
139			(this has the effect of jumping back into the Event loop once to serve new
140			events).
141
142			The reason this function exists is that you sometimes want to serve events
143			while doing other work. Calling C<Coro::cede> does not work because
144			C<cede> implies that the current coroutine is runnable and does not call
145			into the Event dispatcher.
146
147			=cut
148
149			sub sweep {
150	root	1.7	Event::one_event(0); # for now
151	root	1.1	}
152
153			=item $result = loop([$timeout])
154
155			This is the version of C<loop> you should use instead of C<Event::loop>
156			when using this module - it will ensure correct scheduling in the presence
157			of events.
158
159			=item unloop([$result])
160
161			Same as Event::unloop (provided here for your convinience only).
162
163			=cut
164
165	root	1.40	$Coro::idle = \&Event::one_event; # inefficient
166	root	1.9
167	root	1.1	1;
168
169	root	1.36	=back
170
171	root	1.1	=head1 AUTHOR
172
173	root	1.27	Marc Lehmann <schmorp@schmorp.de>
174	root	1.25	http://home.schmorp.de/
175	root	1.1
176			=cut
177