ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro.pm
(Generate patch)

Comparing Coro/Coro.pm (file contents):
Revision 1.1 by root, Tue Jul 3 02:53:34 2001 UTC vs.
Revision 1.19 by root, Sat Jul 21 03:44:06 2001 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - create an manage coroutines 3Coro - coroutine process abstraction
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Coro; 7 use Coro;
8 8
9 async {
10 # some asynchronous thread of execution
11 };
12
13 # alternatively create an async process like this:
14
15 sub some_func : Coro {
16 # some more async code
17 }
18
19 yield;
20
9=head1 DESCRIPTION 21=head1 DESCRIPTION
10 22
23This module collection manages coroutines. Coroutines are similar to
24Threads but don't run in parallel.
25
26This module is still experimental, see the BUGS section below.
27
28=cut
29
30package Coro;
31
32use Coro::State;
33
34use base Exporter;
35
36$VERSION = 0.09;
37
38@EXPORT = qw(async yield schedule terminate current);
39@EXPORT_OK = qw($current);
40
41{
42 use subs 'async';
43
44 my @async;
45
46 # this way of handling attributes simply is NOT scalable ;()
47 sub import {
48 Coro->export_to_level(1, @_);
49 my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE};
50 *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub {
51 my ($package, $ref) = (shift, shift);
52 my @attrs;
53 for (@_) {
54 if ($_ eq "Coro") {
55 push @async, $ref;
56 } else {
57 push @attrs, $_;
58 }
59 }
60 return $old ? $old->($package, $ref, @attrs) : @attrs;
61 };
62 }
63
64 sub INIT {
65 async pop @async while @async;
66 }
67}
68
69=item $main
70
71This coroutine represents the main program.
72
73=cut
74
75our $main = new Coro;
76
77=item $current (or as function: current)
78
79The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).
80
81=cut
82
83# maybe some other module used Coro::Specific before...
84if ($current) {
85 $main->{specific} = $current->{specific};
86}
87
88our $current = $main;
89
90sub current() { $current }
91
92=item $idle
93
94The coroutine to switch to when no other coroutine is running. The default
95implementation prints "FATAL: deadlock detected" and exits.
96
97=cut
98
99# should be done using priorities :(
100our $idle = new Coro sub {
101 print STDERR "FATAL: deadlock detected\n";
102 exit(51);
103};
104
105# we really need priorities...
106my @ready; # the ready queue. hehe, rather broken ;)
107
108# static methods. not really.
109
110=head2 STATIC METHODS
111
112Static methods are actually functions that operate on the current process only.
113
11=over 4 114=over 4
12 115
13=cut 116=item async { ... } [@args...]
14 117
15package Coro; 118Create a new asynchronous process and return it's process object
119(usually unused). When the sub returns the new process is automatically
120terminated.
16 121
17BEGIN { 122 # create a new coroutine that just prints its arguments
18 $VERSION = 0.01; 123 async {
124 print "@_\n";
125 } 1,2,3,4;
19 126
20 require XSLoader; 127The coderef you submit MUST NOT be a closure that refers to variables
21 XSLoader::load Coro, $VERSION; 128in an outer scope. This does NOT work. Pass arguments into it instead.
22}
23 129
24=item $main
25
26This coroutine represents the main program.
27
28=item $current
29
30The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).
31
32=cut 130=cut
33 131
34$main = $current = _newprocess { 132sub async(&@) {
35 # never being called 133 my $pid = new Coro @_;
36}; 134 $pid->ready;
135 $pid;
136}
37 137
38=item $error, $error_msg, $error_coro 138=item schedule
39 139
40This coroutine will be called on fatal errors. C<$error_msg> and 140Calls the scheduler. Please note that the current process will not be put
41C<$error_coro> return the error message and the error-causing coroutine, 141into the ready queue, so calling this function usually means you will
42respectively. 142never be called again.
43 143
44=cut 144=cut
45 145
46$error_msg = 146my $prev;
47$error_coro = undef;
48 147
49$error = _newprocess { 148sub schedule {
50 print STDERR "FATAL: $error_msg, program aborted\n"; 149 # should be done using priorities :(
51 exit 250; 150 ($prev, $current) = ($current, shift @ready || $idle);
52}; 151 Coro::State::transfer($prev, $current);
152}
53 153
54=item $coro = new $coderef [, @args] 154=item yield
55 155
56Create a new coroutine and return it. The first C<resume> call to this 156Yield to other processes. This function puts the current process into the
57coroutine will start execution at the given coderef. If it returns it 157ready queue and calls C<schedule>.
58should return a coroutine to switch to. If, after returning, the coroutine
59is C<resume>d again it starts execution again at the givne coderef.
60 158
61=cut 159=cut
160
161sub yield {
162 $current->ready;
163 &schedule;
164}
165
166=item terminate
167
168Terminates the current process.
169
170Future versions of this function will allow result arguments.
171
172=cut
173
174sub terminate {
175 $current->{_results} = [@_];
176 &schedule;
177}
178
179=back
180
181# dynamic methods
182
183=head2 PROCESS METHODS
184
185These are the methods you can call on process objects.
186
187=over 4
188
189=item new Coro \&sub [, @args...]
190
191Create a new process and return it. When the sub returns the process
192automatically terminates. To start the process you must first put it into
193the ready queue by calling the ready method.
194
195The coderef you submit MUST NOT be a closure that refers to variables
196in an outer scope. This does NOT work. Pass arguments into it instead.
197
198=cut
199
200sub _newcoro {
201 terminate &{+shift};
202}
62 203
63sub new { 204sub new {
64 my $class = $_[0]; 205 my $class = shift;
65 my $proc = $_[1]; 206 bless {
66 bless _newprocess { 207 _coro_state => (new Coro::State $_[0] && \&_newcoro, @_),
67 do {
68 eval { &$proc->resume };
69 if ($@) {
70 ($error_msg, $error_coro) = ($@, $current);
71 $error->resume;
72 }
73 } while ();
74 }, $class; 208 }, $class;
75} 209}
76 210
77=item $coro->resume 211=item $process->ready
78 212
79Resume execution at the given coroutine. 213Put the current process into the ready queue.
80 214
81=cut 215=cut
82 216
83my $prev; 217sub ready {
84 218 push @ready, $_[0];
85sub resume {
86 $prev = $current; $current = $_[0];
87 _transfer($prev, $current);
88} 219}
220
221=back
222
223=cut
89 224
901; 2251;
91 226
92=back 227=head1 BUGS/LIMITATIONS
93 228
94=head1 BUGS 229 - could be faster, especially when the core would introduce special
230 support for coroutines (like it does for threads).
231 - there is still a memleak on coroutine termination that I could not
232 identify. Could be as small as a single SV.
233 - this module is not well-tested.
234 - if variables or arguments "disappear" (become undef) or become
235 corrupted please contact the author so he cen iron out the
236 remaining bugs.
237 - this module is not thread-safe. You must only ever use this module from
238 the same thread (this requirement might be loosened in the future to
239 allow per-thread schedulers, but Coro::Satte does not yet allow this).
95 240
96This module has not yet been extensively tested. 241=head1 SEE ALSO
242
243L<Coro::Channel>, L<Coro::Cont>, L<Coro::Specific>, L<Coro::Semaphore>,
244L<Coro::Signal>, L<Coro::State>, L<Coro::Event>.
97 245
98=head1 AUTHOR 246=head1 AUTHOR
99 247
100 Marc Lehmann <pcg@goof.com> 248 Marc Lehmann <pcg@goof.com>
101 http://www.goof.com/pcg/marc/ 249 http://www.goof.com/pcg/marc/

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines