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 thread 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 threads and then call
C<Event::loop>.

Please note that even programs or modules (such as L<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 multithreading. That means that
you B<MUST NOT> block in an event callback. Again: In Event callbacks,
you I<must never ever> call a Coro function that blocks the current
thread.

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 threads with the same or higher
priority. When any threads 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. Note that for this to work you actually need to
run the event loop in some thread.

=head1 FUNCTIONS

=over 4

=cut

package Coro::Event;

use common::sense;

use Carp;

use Coro;
use Event qw(loop unloop); # we are re-exporting this for historical reasons

use XSLoader;

use base Exporter::;

our @EXPORT = qw(loop unloop sweep);

BEGIN {
   our $VERSION = 6.04;

   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
}

# very inefficient
our $IDLE = new Coro sub {
   while () {
      Event::one_event;
      Coro::schedule if Coro::nready;
   }
};
$IDLE->{desc} = "[Event idle thread]";

$Coro::idle = $IDLE;

1;

=back

=head1 AUTHOR

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

=cut

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