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

Comparing Coro/Coro.pm (file contents):
Revision 1.4 by root, Tue Jul 3 05:05:45 2001 UTC vs.
Revision 1.14 by root, Tue Jul 17 02:21:56 2001 UTC

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

Diff Legend

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